Facile

HTTP & REST

Ces notions ont été abordées en 2e année. Cette page est un rappel des concepts nécessaires pour la suite.

Le protocole HTTP

HTTP (HyperText Transfer Protocol) est le protocole de communication du web. Il fonctionne selon un modèle requête-réponse : un client envoie une requête, le serveur traite et renvoie une réponse.

Chargement du diagramme…

Anatomie d'une requête HTTP

Une requête HTTP contient :

Méthode : l'action à effectuer (GET, POST, etc.)
URL : l'adresse de la ressource (/api/v1/ventes)
Headers : métadonnées (Content-Type, Accept, Authorization)
Body (optionnel) : données envoyées (pour POST, PUT, PATCH)

bash

GET /api/v1/ventes?region=IDF HTTP/1.1
Host: localhost:5000
Accept: application/json

Anatomie d'une réponse HTTP

bash

HTTP/1.1 200 OK
Content-Type: application/json

{
  "data": [...],
  "total": 150
}

Méthodes HTTP

Méthode	Action	Body ?	Idempotent ?
`GET`	Lire une ressource	Non	Oui
`POST`	Créer une ressource	Oui	Non
`PUT`	Remplacer une ressource entière	Oui	Oui
`PATCH`	Modifier partiellement une ressource	Oui	Non*
`DELETE`	Supprimer une ressource	Non	Oui

Idempotent ?

Une requête est idempotente si l'exécuter une ou plusieurs fois produit le même résultat. GET /ventes/42 renvoie toujours la même vente. POST /ventes crée une nouvelle vente à chaque appel.

Codes de statut HTTP

Les codes de statut indiquent le résultat de la requête.

Plage	Signification	Exemples courants
2xx	Succès	`200 OK`, `201 Created`, `204 No Content`
3xx	Redirection	`301 Moved Permanently`, `304 Not Modified`
4xx	Erreur client	`400 Bad Request`, `404 Not Found`, `422 Unprocessable Entity`
5xx	Erreur serveur	`500 Internal Server Error`, `503 Service Unavailable`

En pratique

Pour une API de données, les codes les plus utilisés sont : 200 (succès), 201 (création), 400 (paramètres invalides), 404 (ressource introuvable) et 500 (erreur serveur).

Principes REST

REST (Representational State Transfer) est un style architectural pour les APIs. Ses principes :

Ressources identifiées par des URI : chaque entité a une adresse unique (/api/v1/ventes/42)
Méthodes HTTP explicites : GET pour lire, POST pour créer, etc.
Sans état (stateless) : chaque requête contient toutes les informations nécessaires
Représentations multiples : une même ressource peut être servie en JSON, CSV, XML...

Paramètres d'URL vs Query string

Deux manières de passer des informations dans l'URL :

Paramètres d'URL (path parameters) — pour identifier une ressource :

GET /api/v1/ventes/42
                   ^^
                   ID de la vente

Query string (paramètres de requête) — pour filtrer, paginer, trier :

GET /api/v1/ventes?region=IDF&annee=2024&limit=20
                   ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
                   Filtres et pagination

Règle simple

Path parameters : identification d'une ressource précise (/ventes/42)
Query parameters : filtrage, pagination, tri (?region=IDF&limit=20)

Quelle méthode HTTP est idempotente ?

Quel code de statut HTTP indique que la requête du client contient des paramètres invalides ?

À retenir

Points clés

HTTP fonctionne en requête-réponse avec des méthodes (GET, POST, PUT, DELETE) et des codes de statut
REST structure les APIs autour de ressources identifiées par des URI
Les path parameters identifient une ressource, les query parameters filtrent et paginent
Pour une API de données, les codes 200, 400 et 404 sont les plus fréquents