Conventions API REST

// PUT : on remplace TOUT l'utilisateur
fetch('/api/users/42', {
  method: 'PUT',
  headers: { 'Content-Type': 'application/json' },
  body: JSON.stringify({
    name: 'Arthur',
    email: 'arthur@example.com',
    role: 'admin',
    avatar: 'https://...',
    // Tous les champs doivent être fournis
  }),
});
 
// PATCH : on ne modifie que certains champs
fetch('/api/users/42', {
  method: 'PATCH',
  headers: { 'Content-Type': 'application/json' },
  body: JSON.stringify({ avatar: 'https://...' }),
});

HTTP/1.1 200 OK
Content-Type: application/json
ETag: "a1b2c3d4"
X-Request-ID: req-7f8a9b0c
X-RateLimit-Limit: 100
X-RateLimit-Remaining: 97
X-RateLimit-Reset: 1720000000
Cache-Control: public, max-age=60
Link: <https://api.exemple.com/users?page=2>; rel="next"

GET /api/users?offset=0&limit=20
GET /api/users?offset=20&limit=20

{
  "data": [ ... ],
  "pagination": {
    "offset": 0,
    "limit": 20,
    "total": 150,
    "hasMore": true
  }
}

GET /api/users?cursor=eyJpZCI6NDJ9&limit=20

{
  "data": [ ... ],
  "pagination": {
    "limit": 20,
    "nextCursor": "eyJpZCI6NjJ9",
    "prevCursor": "eyJpZCI6MjJ9"
  }
}

Link: <https://api.exemple.com/users?page=1>; rel="first",
      <https://api.exemple.com/users?page=2>; rel="next",
      <https://api.exemple.com/users?page=8>; rel="last"

{
  "error": {
    "code": "VALIDATION_ERROR",
    "status": 422,
    "message": "La validation a échoué.",
    "details": [
      {
        "field": "email",
        "message": "Cet email est déjà utilisé.",
        "rule": "unique"
      },
      {
        "field": "password",
        "message": "Minimum 8 caractères requis.",
        "rule": "min_length"
      }
    ],
    "requestId": "req-7f8a9b0c"
  }
}

// Traitement côté client
async function apiCall(url, opts = {}) {
  const res = await fetch(url, opts);
 
  if (!res.ok) {
    const body = await res.json();
    const err = body.error || {
      code: 'UNKNOWN',
      status: res.status,
      message: res.statusText,
    };
 
    // Exemple de mapping par code
    switch (err.code) {
      case 'UNAUTHORIZED':
        // Rediriger vers la page de connexion
        window.location.href = '/login';
        break;
      case 'RATE_LIMITED':
        // Attendre le retry
        const retryAfter = res.headers.get('Retry-After');
        setTimeout(() => apiCall(url, opts), retryAfter * 1000);
        return;
    }
 
    throw new APIError(err);
  }
 
  return res.json();
}

GET /api/posts?status=published&author=42&created_after=2025-01-01

GET /api/posts?sort=-published_at,+title

GET /api/posts?q=recherche+en+français&page=1