57bc51290b
- Refactored API endpoint documentation using individual accordions for better clarity. - Added detailed descriptions for `/contents`, `/categories`, `/favorites`, `/reports`, `/api-keys`, `/tags`, `/media`, and `/admin` endpoints. - Improved consistency in query parameters and usage examples.
324 lines
9.5 KiB
Plaintext
324 lines
9.5 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="POST /users/me/2fa/setup">
|
|
Génère un secret et un QR Code pour la configuration de la 2FA.
|
|
</Accordion>
|
|
|
|
<Accordion title="POST /users/me/2fa/enable">
|
|
Active la 2FA après vérification du jeton TOTP.
|
|
</Accordion>
|
|
|
|
<Accordion title="POST /users/me/2fa/disable">
|
|
Désactive la 2FA en utilisant un jeton TOTP valide.
|
|
</Accordion>
|
|
|
|
<Accordion title="GET /users/admin">
|
|
Liste tous les utilisateurs (réservé aux administrateurs).
|
|
**Query Params :** `limit`, `offset`.
|
|
</Accordion>
|
|
|
|
<Accordion title="DELETE /users/:uuid">
|
|
Supprime définitivement un utilisateur par son UUID (réservé aux administrateurs).
|
|
</Accordion>
|
|
</Accordions>
|
|
|
|
### 🖼️ Contenus (`/contents`)
|
|
|
|
<Accordions>
|
|
<Accordion title="GET /contents/explore">
|
|
Recherche et filtre les contenus. Cet endpoint est mis en cache.
|
|
|
|
**Query Params :**
|
|
- `limit` (number) : Défaut 10.
|
|
- `offset` (number) : Défaut 0.
|
|
- `sort` : `trend` | `recent`
|
|
- `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/trends">
|
|
Récupère les contenus les plus populaires du moment.
|
|
</Accordion>
|
|
|
|
<Accordion title="GET /contents/recent">
|
|
Récupère les contenus les plus récents.
|
|
</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">
|
|
Incrémente le compteur de vues d'un contenu.
|
|
</Accordion>
|
|
|
|
<Accordion title="POST /contents/:id/use">
|
|
Incrémente le compteur d'utilisation d'un contenu.
|
|
</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 (`/categories`)
|
|
|
|
<Accordions>
|
|
<Accordion title="GET /categories">
|
|
Liste toutes les catégories de mèmes disponibles.
|
|
</Accordion>
|
|
|
|
<Accordion title="GET /categories/:id">
|
|
Récupère les détails d'une catégorie spécifique.
|
|
</Accordion>
|
|
|
|
<Accordion title="POST /categories">
|
|
Crée une nouvelle catégorie (**Admin uniquement**).
|
|
</Accordion>
|
|
|
|
<Accordion title="PATCH /categories/:id">
|
|
Met à jour une catégorie existante (**Admin uniquement**).
|
|
</Accordion>
|
|
|
|
<Accordion title="DELETE /categories/:id">
|
|
Supprime une catégorie (**Admin uniquement**).
|
|
</Accordion>
|
|
</Accordions>
|
|
|
|
### ⭐ Favoris (`/favorites`)
|
|
|
|
<Accordions>
|
|
<Accordion title="GET /favorites">
|
|
Liste les favoris de l'utilisateur connecté.
|
|
**Query Params :** `limit`, `offset`.
|
|
</Accordion>
|
|
|
|
<Accordion title="POST /favorites/:contentId">
|
|
Ajoute un contenu aux favoris de l'utilisateur.
|
|
</Accordion>
|
|
|
|
<Accordion title="DELETE /favorites/:contentId">
|
|
Retire un contenu des favoris de l'utilisateur.
|
|
</Accordion>
|
|
</Accordions>
|
|
|
|
### 🚩 Signalements (`/reports`)
|
|
|
|
<Accordions>
|
|
<Accordion title="POST /reports">
|
|
Signale un contenu ou un tag inapproprié.
|
|
</Accordion>
|
|
|
|
<Accordion title="GET /reports">
|
|
Liste tous les signalements (**Admin/Modérateurs uniquement**).
|
|
**Query Params :** `limit`, `offset`.
|
|
</Accordion>
|
|
|
|
<Accordion title="PATCH /reports/:id/status">
|
|
Change le statut d'un signalement (`pending`, `resolved`, `dismissed`) (**Admin/Modérateurs uniquement**).
|
|
</Accordion>
|
|
</Accordions>
|
|
|
|
### 🔑 Clés API (`/api-keys`)
|
|
|
|
<Accordions>
|
|
<Accordion title="POST /api-keys">
|
|
Génère une nouvelle clé API pour l'utilisateur.
|
|
**Corps :** `{ name, expiresAt? }`.
|
|
</Accordion>
|
|
|
|
<Accordion title="GET /api-keys">
|
|
Liste toutes les clés API actives de l'utilisateur.
|
|
</Accordion>
|
|
|
|
<Accordion title="DELETE /api-keys/:id">
|
|
Révoque une clé API spécifique.
|
|
</Accordion>
|
|
</Accordions>
|
|
|
|
### 🏷️ Tags (`/tags`)
|
|
|
|
<Accordions>
|
|
<Accordion title="GET /tags">
|
|
Recherche et liste les tags populaires ou récents.
|
|
**Query Params :** `query`, `sort` (`popular` | `recent`), `limit`, `offset`.
|
|
</Accordion>
|
|
</Accordions>
|
|
|
|
### 🛠️ Système (`/health`)
|
|
|
|
<Accordions>
|
|
<Accordion title="GET /health">
|
|
Vérifie l'état de santé de l'API et de ses dépendances (Base de données, Redis, etc.).
|
|
</Accordion>
|
|
</Accordions>
|
|
|
|
### 📁 Médias (`/media`)
|
|
|
|
<Accordions>
|
|
<Accordion title="GET /media">
|
|
Accès direct aux fichiers multimédias.
|
|
**Query Param :** `path` (clé du fichier sur S3).
|
|
</Accordion>
|
|
</Accordions>
|
|
|
|
### 📊 Administration (`/admin`)
|
|
|
|
<Accordions>
|
|
<Accordion title="GET /admin/stats">
|
|
Récupère les statistiques globales d'utilisation de la plateforme (**Admin uniquement**).
|
|
</Accordion>
|
|
</Accordions>
|