249 lines
8.3 KiB
Plaintext
249 lines
8.3 KiB
Plaintext
---
|
|
title: Référence API
|
|
description: Documentation détaillée de tous les points de terminaison de l'API Memegoat.
|
|
---
|
|
|
|
## 📖 Référence API
|
|
|
|
Cette page documente tous les points de terminaison disponibles sur l'API Memegoat. L'URL de base de l'API est `https://api.memegoat.fr`.
|
|
|
|
<Callout type="info">
|
|
L'authentification est gérée via des **cookies HttpOnly sécurisés** (`iron-session`). Les tokens ne sont pas exposés dans le corps des réponses après connexion pour une sécurité maximale.
|
|
</Callout>
|
|
|
|
### 🔐 Authentification (`/auth`)
|
|
|
|
<Accordions>
|
|
<Accordion title="POST /auth/register">
|
|
Inscrit un nouvel utilisateur.
|
|
|
|
**Corps de la requête (JSON) :**
|
|
- `username` (string) : Nom d'utilisateur unique.
|
|
- `email` (string) : Adresse email valide.
|
|
- `password` (string) : Mot de passe (min. 8 caractères).
|
|
|
|
```json
|
|
{
|
|
"username": "goat_user",
|
|
"email": "user@memegoat.fr",
|
|
"password": "strong-password"
|
|
}
|
|
```
|
|
</Accordion>
|
|
|
|
<Accordion title="POST /auth/login">
|
|
Authentifie un utilisateur et retourne les jetons de session. Si la 2FA est activée, retourne un indicateur.
|
|
|
|
**Corps de la requête :**
|
|
- `email` (string)
|
|
- `password` (string)
|
|
|
|
**Réponse (Succès) :**
|
|
```json
|
|
{
|
|
"message": "User logged in successfully",
|
|
"userId": "uuid-v4"
|
|
}
|
|
```
|
|
*Note: L'access_token et le refresh_token sont stockés dans un cookie HttpOnly chiffré.*
|
|
|
|
**Réponse (2FA requise) :**
|
|
```json
|
|
{
|
|
"message": "2FA required",
|
|
"requires2FA": true,
|
|
"userId": "uuid-v4"
|
|
}
|
|
```
|
|
</Accordion>
|
|
|
|
<Accordion title="POST /auth/verify-2fa">
|
|
Finalise la connexion si la 2FA est requise.
|
|
|
|
**Corps de la requête :**
|
|
- `userId` (uuid) : ID de l'utilisateur.
|
|
- `token` (string) : Code TOTP à 6 chiffres.
|
|
</Accordion>
|
|
|
|
<Accordion title="POST /auth/refresh">
|
|
Obtient un nouvel `access_token` à partir du `refresh_token` stocké dans la session.
|
|
Met à jour automatiquement le cookie de session.
|
|
</Accordion>
|
|
|
|
<Accordion title="POST /auth/logout">
|
|
Invalide la session actuelle.
|
|
</Accordion>
|
|
</Accordions>
|
|
|
|
### 👤 Utilisateurs (`/users`)
|
|
|
|
<Accordions>
|
|
<Accordion title="GET /users/me">
|
|
Récupère les informations détaillées de l'utilisateur connecté. Requiert l'authentification.
|
|
</Accordion>
|
|
|
|
<Accordion title="GET /users/public/:username">
|
|
Récupère le profil public d'un utilisateur par son nom d'utilisateur.
|
|
**Réponse :** `id`, `username`, `displayName`, `avatarUrl`, `createdAt`.
|
|
</Accordion>
|
|
|
|
<Accordion title="GET /users/me/export">
|
|
Extrait l'intégralité des données de l'utilisateur au format JSON (Conformité RGPD).
|
|
Contient le profil, les contenus et les favoris.
|
|
</Accordion>
|
|
|
|
<Accordion title="PATCH /users/me">
|
|
Met à jour les informations du profil.
|
|
**Corps :**
|
|
- `displayName` (string)
|
|
- `bio` (string)
|
|
</Accordion>
|
|
|
|
<Accordion title="POST /users/me/avatar">
|
|
Met à jour l'avatar de l'utilisateur.
|
|
**Type :** `multipart/form-data`
|
|
**Champ :** `file` (Image)
|
|
</Accordion>
|
|
|
|
<Accordion title="PATCH /users/me/consent">
|
|
Met à jour les consentements légaux de l'utilisateur.
|
|
**Corps :**
|
|
- `termsVersion` (string)
|
|
- `privacyVersion` (string)
|
|
</Accordion>
|
|
|
|
<Accordion title="DELETE /users/me">
|
|
Marque le compte pour suppression (Soft Delete).
|
|
<Callout type="warn">
|
|
Les données sont définitivement purgées après un délai légal de 30 jours.
|
|
</Callout>
|
|
</Accordion>
|
|
|
|
<Accordion title="Gestion 2FA">
|
|
- `POST /users/me/2fa/setup` : Génère un secret et QR Code.
|
|
- `POST /users/me/2fa/enable` : Active après vérification du jeton.
|
|
- `POST /users/me/2fa/disable` : Désactive avec jeton.
|
|
</Accordion>
|
|
|
|
<Accordion title="Administration (Admin uniquement)">
|
|
- `GET /users/admin` : Liste tous les utilisateurs (avec pagination `limit`, `offset`).
|
|
- `DELETE /users/:uuid` : Supprime définitivement un utilisateur par son UUID.
|
|
</Accordion>
|
|
</Accordions>
|
|
|
|
### 🖼️ Contenus (`/contents`)
|
|
|
|
<Accordions>
|
|
<Accordion title="GET /contents/explore | /trends | /recent">
|
|
Recherche et filtre les contenus. Ces endpoints sont mis en cache (Redis + Navigateur).
|
|
|
|
**Query Params :**
|
|
- `limit` (number) : Défaut 10.
|
|
- `offset` (number) : Défaut 0.
|
|
- `sort` : `trend` | `recent` (uniquement sur `/explore`)
|
|
- `tag` (string) : Filtrer par tag.
|
|
- `category` (slug ou id) : Filtrer par catégorie.
|
|
- `author` (username) : Filtrer par auteur.
|
|
- `query` (titre) : Recherche textuelle.
|
|
- `favoritesOnly` (bool) : Ne montrer que les favoris de l'utilisateur connecté.
|
|
- `userId` (uuid) : Filtrer les contenus d'un utilisateur spécifique.
|
|
</Accordion>
|
|
|
|
<Accordion title="GET /contents/:idOrSlug">
|
|
Récupère un contenu par son ID ou son Slug.
|
|
|
|
**Détection de Bots (SEO) :**
|
|
Si l'User-Agent correspond à un robot d'indexation (Googlebot, Twitterbot, etc.), l'API retourne un rendu HTML minimal contenant les méta-tags **OpenGraph** et **Twitter Cards** pour un partage optimal. Pour les autres clients, les données sont retournées en JSON.
|
|
</Accordion>
|
|
|
|
<Accordion title="POST /contents">
|
|
Crée une entrée de contenu (sans upload de fichier direct). Utile pour référencer des URLs externes.
|
|
**Corps :** `title`, `description`, `url`, `type`, `categoryId`, `tags`.
|
|
</Accordion>
|
|
|
|
<Accordion title="POST /contents/upload">
|
|
Upload un fichier avec traitement automatique par le serveur.
|
|
**Type :** `multipart/form-data`
|
|
|
|
**Champs :**
|
|
- `file` (binary) : png, jpeg, webp, webm, gif.
|
|
- `type` : `meme` | `gif`
|
|
- `title` : string
|
|
- `categoryId`? : uuid
|
|
- `tags`? : string[]
|
|
</Accordion>
|
|
|
|
<Accordion title="POST /contents/upload-url">
|
|
Génère une URL présignée pour un upload direct vers S3.
|
|
**Query Param :** `fileName` (string).
|
|
</Accordion>
|
|
|
|
<Accordion title="POST /contents/:id/view | /use">
|
|
Incrémente les statistiques de vue ou d'utilisation.
|
|
</Accordion>
|
|
|
|
<Accordion title="DELETE /contents/:id">
|
|
Supprime un contenu (Soft Delete). Doit être l'auteur.
|
|
</Accordion>
|
|
|
|
<Accordion title="DELETE /contents/:id/admin">
|
|
Supprime définitivement un contenu. **Réservé aux administrateurs.**
|
|
</Accordion>
|
|
</Accordions>
|
|
|
|
### 📂 Catégories, ⭐ Favoris, 🚩 Signalements
|
|
|
|
<Accordions>
|
|
<Accordion title="Catégories (/categories)">
|
|
- `GET /categories` : Liste toutes les catégories.
|
|
- `GET /categories/:id` : Détails d'une catégorie.
|
|
- `POST /categories` : Création (Admin uniquement).
|
|
- `PATCH /categories/:id` : Mise à jour (Admin uniquement).
|
|
- `DELETE /categories/:id` : Suppression (Admin uniquement).
|
|
</Accordion>
|
|
|
|
<Accordion title="Favoris (/favorites)">
|
|
Requiert l'authentification.
|
|
- `GET /favorites` : Liste les favoris de l'utilisateur (avec pagination `limit`, `offset`).
|
|
- `POST /favorites/:contentId` : Ajoute un favori.
|
|
- `DELETE /favorites/:contentId` : Retire un favori.
|
|
</Accordion>
|
|
|
|
<Accordion title="Signalements (/reports)">
|
|
- `POST /reports` : Signale un contenu ou un tag.
|
|
- `GET /reports` : Liste des signalements (Pagination `limit`, `offset`). **Admin/Modérateurs**.
|
|
- `PATCH /reports/:id/status` : Change le statut (`pending`, `resolved`, `dismissed`). **Admin/Modérateurs**.
|
|
</Accordion>
|
|
</Accordions>
|
|
|
|
### 🔑 Clés API & 🏷️ Tags
|
|
|
|
<Accordions>
|
|
<Accordion title="Clés API (/api-keys)">
|
|
- `POST /api-keys` : Génère une clé `{ name, expiresAt? }`.
|
|
- `GET /api-keys` : Liste les clés actives.
|
|
- `DELETE /api-keys/:id` : Révoque une clé.
|
|
</Accordion>
|
|
|
|
<Accordion title="Tags (/tags)">
|
|
- `GET /tags` : Recherche de tags.
|
|
- **Params :** `query` (recherche), `sort` (`popular` | `recent`), `limit`, `offset`.
|
|
</Accordion>
|
|
</Accordions>
|
|
|
|
### 🛠️ Système & Médias
|
|
|
|
<Accordions>
|
|
<Accordion title="Santé (/health)">
|
|
- `GET /health` : Vérifie l'état de l'API et de la connexion à la base de données.
|
|
</Accordion>
|
|
|
|
<Accordion title="Médias (/media)">
|
|
- `GET /media/*key` : Accès direct aux fichiers stockés sur S3. Supporte la mise en cache agressive.
|
|
</Accordion>
|
|
|
|
<Accordion title="Administration (/admin)">
|
|
- `GET /admin/stats` : Récupère les statistiques globales de la plateforme. **Admin uniquement**.
|
|
</Accordion>
|
|
</Accordions>
|