HTTP & REST : les bases

L'idée clé

Quand un navigateur (ou ton appli mobile) demande quelque chose à un serveur, il envoie une requête HTTP. Le serveur répond avec une réponse HTTP. Une requête, c'est essentiellement :

• Un verbe (GET, POST, PATCH, etc.) — décrit l'intention
• Une URL (/api/bugs/dev-tour/BUG-001) — décrit la cible
• Optionnellement un body (JSON, formulaire, fichier)
• Des headers (auth, content-type, etc.)

REST est une convention pour structurer ça proprement.

Les 5 verbes à connaître

Idempotent veut dire : refaire la même requête plusieurs fois donne le même résultat. Un POST ne l'est pas (crée plusieurs ressources), un PATCH l'est en général (met la même valeur), un DELETE aussi (la 2e fois, déjà supprimé).

Les status codes

La réponse a un code à 3 chiffres qui dit comment ça s'est passé :

• 2xx — Succès : 200 OK, 201 Created (après un POST), 204 No Content (suppression réussie sans body)
• 3xx — Redirection : 301, 302, 307
• 4xx — Erreur côté client : 400 Bad Request (JSON malformé), 401 Unauthorized (pas connecté), 403 Forbidden (connecté mais pas le droit), 404 Not Found, 409 Conflict, 429 Too Many Requests
• 5xx — Erreur côté serveur : 500 Internal Server Error, 502 Bad Gateway, 503 Service Unavailable

Règle : si tu retournes 200 quand un user envoie n'importe quoi, tu rates ta job. Sois précis.

REST — la convention

Une API REST organise ses URLs en ressources (noms, pas verbes) et utilise les verbes HTTP pour les actions :

GET    /api/bugs              → lister les bugs
POST   /api/bugs              → créer un bug
GET    /api/bugs/wari/BUG-3   → lire un bug
PATCH  /api/bugs/wari/BUG-3   → modifier
DELETE /api/bugs/wari/BUG-3   → supprimer

GET    /api/bugs              → lister les bugs
POST   /api/bugs              → créer un bug
GET    /api/bugs/wari/BUG-3   → lire un bug
PATCH  /api/bugs/wari/BUG-3   → modifier
DELETE /api/bugs/wari/BUG-3   → supprimer

Anti-pattern classique :

POST /api/createBug    ❌ (le verbe est dans l'URL)
POST /api/getBugs      ❌ (POST pour lire ?)

POST /api/createBug    ❌ (le verbe est dans l'URL)
POST /api/getBugs      ❌ (POST pour lire ?)

L'URL nomme la ressource ; le verbe dit ce qu'on lui fait. C'est ce qu'on a appliqué dans le tracker dev-tour : /api/bugs/{project}/{id} avec les 5 verbes selon l'action.

Côté Next.js

Un fichier app/api/bugs/route.ts exporte une fonction nommée par verbe. Next appelle automatiquement la bonne :

export async function GET(req: Request) { ... }
export async function POST(req: Request) { ... }
export async function PATCH(req: Request) { ... }
export async function DELETE(req: Request) { ... }

export async function GET(req: Request) { ... }
export async function POST(req: Request) { ... }
export async function PATCH(req: Request) { ... }
export async function DELETE(req: Request) { ... }

Pas besoin de routeur intermédiaire (express, fastify, etc.) — c'est intégré.

Côté Python (référence pour toi)

Si tu as fait du Flask :

@app.route("/api/bugs", methods=["POST"])
def create_bug():
    ...

@app.route("/api/bugs", methods=["POST"])
def create_bug():
    ...

Équivalent Next.js :

export async function POST(req: Request) { ... }

export async function POST(req: Request) { ... }

Même idée, syntaxe différente. Next colocalise par fichier (un dossier = une URL), Flask par décorateur.

Pour aller plus loin

Headers utiles : Content-Type (format du body), Authorization (Bearer token), Accept (format de réponse souhaité), Cache-Control (durée de cache).