Aller au contenu

REST API Design

Principe

REST (Representational State Transfer) est un style d'architecture pour les APIs basé sur les ressources et les verbes HTTP.

Une API REST bien conçue est :

  • prévisible — les URLs suivent une convention
  • stateless — chaque requête contient toute l'information nécessaire
  • uniforme — les mêmes verbes HTTP pour toutes les ressources

Conventions de nommage

URLs

GET    /api/v1/users          → liste des utilisateurs
GET    /api/v1/users/42       → utilisateur 42
POST   /api/v1/users          → créer un utilisateur
PUT    /api/v1/users/42       → remplacer l'utilisateur 42
PATCH  /api/v1/users/42       → modifier partiellement
DELETE /api/v1/users/42       → supprimer

Règles :

  • noms au pluriel (/users, pas /user)
  • pas de verbes dans l'URL (/users, pas /getUsers)
  • kebab-case pour les mots composés (/order-items)
  • hiérarchie pour les sous-ressources (/users/42/orders)

Verbes HTTP

Verbe Action Idempotent Body
GET Lire Oui Non
POST Créer Non Oui
PUT Remplacer Oui Oui
PATCH Modifier partiellement Non Oui
DELETE Supprimer Oui Non

Codes de retour

Succès

Code Signification Usage
200 OK GET, PUT, PATCH réussis
201 Created POST réussi, ressource créée
204 No Content DELETE réussi

Erreurs client

Code Signification Usage
400 Bad Request Validation échouée
401 Unauthorized Non authentifié
403 Forbidden Pas les droits
404 Not Found Ressource inexistante
409 Conflict Conflit (ex : doublon)
422 Unprocessable Entity Données valides mais non traitables

Erreurs serveur

Code Signification Usage
500 Internal Server Error Erreur non prévue
502 Bad Gateway Service en aval indisponible
503 Service Unavailable Surcharge temporaire

Pagination

GET /api/v1/users?page=2&size=20

Réponse avec métadonnées :

{
  "content": [...],
  "page": 2,
  "size": 20,
  "totalElements": 156,
  "totalPages": 8
}

Alternatives :

  • offset-based : ?offset=40&limit=20 — simple mais problématique pour les grands datasets
  • cursor-based : ?cursor=abc123&limit=20 — performant, adapté aux flux temps réel

Filtrage et tri

GET /api/v1/users?status=active&role=admin&sort=createdAt,desc

Conventions :

  • filtres en query params
  • tri avec sort=field,direction
  • recherche avec ?q=terme

Versioning

Stratégie Exemple Avantage
URL path /api/v1/users Simple, explicite
Header Accept: application/vnd.api.v1+json URL propre
Query param /api/users?version=1 Facile à tester

Le versioning par URL est le plus courant et le plus lisible.

Format d'erreur

Structure cohérente pour toutes les erreurs :

{
  "status": 400,
  "error": "Bad Request",
  "message": "Le champ email est invalide",
  "timestamp": "2026-01-15T10:30:00Z",
  "path": "/api/v1/users"
}

HATEOAS

Hypermedia as the Engine of Application State — les réponses contiennent les liens vers les actions possibles :

{
  "id": 42,
  "name": "Ali",
  "_links": {
    "self": "/api/v1/users/42",
    "orders": "/api/v1/users/42/orders",
    "delete": "/api/v1/users/42"
  }
}

Utile en théorie, rarement implémenté complètement en pratique.

À retenir

  • REST est une convention, pas un protocole — la cohérence est clé
  • les codes HTTP doivent être utilisés correctement (pas tout en 200)
  • la pagination est obligatoire pour les collections
  • le format d'erreur doit être uniforme sur toute l'API
  • le versioning doit être prévu dès le début

Voir aussi