memegoat/documentation/content/docs/api-reference.mdx

---
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/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.
    - `displayName` (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 (GET /users/admin)">
    Liste tous les utilisateurs. Réservé aux administrateurs.
    **Params :** `limit`, `offset`.
  </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 :**
    - `sort` : `trend` | `recent` (uniquement sur `/explore`)
    - `tag` (string)
    - `category` (slug ou id)
    - `author` (username)
    - `query` (titre)
    - `favoritesOnly` (bool)
  </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/upload">
    Upload un fichier avec traitement automatique.
    **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/: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>
</Accordions>

### 📂 Catégories, ⭐ Favoris, 🚩 Signalements

<Accordions>
  <Accordion title="Catégories (/categories)">
    - `GET /categories` : Liste toutes les catégories.
    - `POST /categories` : Création (Admin uniquement).
  </Accordion>

  <Accordion title="Favoris (/favorites)">
    - `GET /favorites` : Liste les favoris de l'utilisateur.
    - `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 (Modérateurs).
    - `PATCH /reports/:id/status` : Gère le workflow.
  </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 populaires ou récents.
    **Params :** `query`, `sort`, `limit`.
  </Accordion>
</Accordions>