API REST

REST (Representational State Transfer) est un style d’architecture pour concevoir des APIs web. Ce n’est pas un protocole — c’est un ensemble de contraintes à respecter lors de la conception.

REST repose sur HTTP.
Pour les méthodes, codes de statut et headers → HTTP — Méthodes, Codes et Headers
Pour la structure bas niveau des requêtes → Requêtes HTTP et HTTPS

---

Les 6 contraintes REST

Contrainte	Signification	Conséquence pratique
Stateless	Le serveur ne garde aucun état de session client	Chaque requête est autonome — toutes les infos nécessaires sont dans la requête (token, paramètres…)
Client-Serveur	Séparation claire des responsabilités	Le client gère l’UI, le serveur gère les données
Interface uniforme	URLs cohérentes, méthodes HTTP standard	Prévisibilité pour les consommateurs de l’API
Layered System	Le client ne sait pas si c’est le serveur final qui répond	Proxy, cache, load balancer transparents
Cacheable	Les réponses peuvent être mises en cache	Headers Cache-Control, ETag, Last-Modified
Code on demand	(Optionnel) Le serveur peut envoyer du code exécutable	Peu utilisé en pratique

---

Modélisation par ressources

En REST, tout est une ressource identifiée par une URL. Les actions sont exprimées par les méthodes HTTP.

Ressource : /users            (collection)
Ressource : /users/42         (ressource individuelle)
Ressource : /users/42/orders  (sous-ressource)

Méthode	URL	Action REST
GET	/users	Lister tous les utilisateurs
GET	/users/42	Lire l’utilisateur 42
POST	/users	Créer un utilisateur
PUT	/users/42	Remplacer l’utilisateur 42 (complet)
PATCH	/users/42	Modifier partiellement l’utilisateur 42
DELETE	/users/42	Supprimer l’utilisateur 42

Référence complète des méthodes, idempotence et codes de statut → HTTP — Méthodes, Codes et Headers

---

Exemple complet d’une API REST

# Créer un utilisateur
curl -X POST https://api.exemple.com/v1/users \
  -H "Authorization: Bearer eyJ..." \
  -H "Content-Type: application/json" \
  -d '{"name": "Alice", "email": "alice@exemple.com", "role": "admin"}'
 
# Réponse 201 Created
{
  "id": "usr_abc123",
  "name": "Alice",
  "email": "alice@exemple.com",
  "role": "admin",
  "created_at": "2026-04-05T13:00:00Z"
}
 
# Lire l'utilisateur
curl -X GET https://api.exemple.com/v1/users/usr_abc123 \
  -H "Authorization: Bearer eyJ..."
 
# Modifier partiellement
curl -X PATCH https://api.exemple.com/v1/users/usr_abc123 \
  -H "Authorization: Bearer eyJ..." \
  -H "Content-Type: application/json" \
  -d '{"role": "viewer"}'
 
# Supprimer
curl -X DELETE https://api.exemple.com/v1/users/usr_abc123 \
  -H "Authorization: Bearer eyJ..."
# → 204 No Content

---

Versioning

Le versioning permet de faire évoluer l’API sans casser les clients existants.

Stratégie	Exemple	Avantages	Inconvénients
URL path	/v1/users, /v2/users	Simple, visible, cacheable	Pollue les URLs
Header	Accept: application/vnd.api+json;version=2	URLs propres	Moins découvrable
Query param	/users?version=2	Simple à tester	Pollue les requêtes
Subdomain	v2.api.exemple.com	Isolation complète	Infrastructure complexe

La stratégie URL path (/v1/) est la plus répandue et recommandée pour les APIs publiques.

---

Pagination

Pour les collections volumineuses, les réponses doivent être paginées.

// Offset pagination (classique)
GET /v1/users?page=2&limit=20
 
{
  "data": [...],
  "pagination": {
    "page": 2,
    "limit": 20,
    "total": 150,
    "total_pages": 8
  }
}
 
// Cursor pagination (recommandé pour le temps réel)
GET /v1/users?cursor=dXNlcl8x&limit=20
 
{
  "data": [...],
  "next_cursor": "dXNlcl8y",
  "has_more": true
}

La cursor pagination est préférable quand les données changent souvent (évite les doublons/sauts lors de suppressions).

---

Filtrage, tri et sélection de champs

# Filtres
GET /v1/users?role=admin&status=active
 
# Tri
GET /v1/users?sort=created_at&order=desc
 
# Sélection de champs (field selection)
GET /v1/users?fields=id,name,email
 
# Recherche full-text
GET /v1/users?search=alice

---

Bonnes pratiques REST

✅ À faire                           ❌ À éviter
────────────────────────────         ────────────────────────────
/users                               /getUsers
/users/42                            /getUserById?id=42
/users/42/orders                     /getUserOrders?userId=42
Noms en minuscules, pluriel          Verbes dans les URLs
Retourner l'objet créé (201)         Retourner 200 pour tout
Utiliser les bons codes HTTP         Tout en 200 avec {error: ...}
Versionner l'API dès le départ       Casser les clients existants
Documenter avec OpenAPI/Swagger      Pas de documentation

---

OpenAPI / Swagger

OpenAPI est le standard de documentation pour les APIs REST. Il décrit les endpoints, paramètres et réponses dans un fichier YAML/JSON.

# openapi.yaml
openapi: "3.0.0"
info:
  title: User API
  version: "1.0"
paths:
  /users:
    get:
      summary: Liste tous les utilisateurs
      parameters:
        - name: role
          in: query
          schema:
            type: string
      responses:
        "200":
          description: Liste d'utilisateurs
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: "#/components/schemas/User"

---

En relation avec

• API — Vue d’ensemble — comparatif des types d’API
• HTTP — Méthodes, Codes et Headers — référence méthodes, codes, headers, CORS
• API GraphQL — alternative REST pour les besoins de requêtes flexibles
• Requêtes HTTP et HTTPS — structure bas niveau du protocole HTTP
• Authentification API — sécuriser les endpoints REST