Utiliser JSON dans les API REST : bonnes pratiques

2026-07-19· Tags: json, rest-api, api-design, json-best-practices, pagination, web-development

JSON dans les API REST

JSON et les API REST sont faits l'un pour l'autre. La syntaxe légère de JSON, sa prise en charge native des tableaux et son support universel dans tous les langages en font le format par défaut des API web modernes. Mais simplement utiliser JSON dans votre API ne suffit pas -- suivre les conventions établies et les bonnes pratiques garantit que votre API est cohérente, intuitive et facile à intégrer.

Format des requêtes et des réponses

Structure d'enveloppe cohérente

Adoptez une enveloppe JSON cohérente pour toutes les réponses de l'API. Cela rend le traitement côté client prévisible et simplifie la gestion des erreurs.

{
  "status": "success",
  "data": {
    "user": {
      "id": 123,
      "name": "Alice",
      "email": "alice@example.com"
    }
  },
  "meta": {
    "requestId": "req-a1b2c3d4",
    "timestamp": "2026-07-19T10:30:00Z"
  }
}

Snake Case contre Camel Case

Choisissez une convention de nommage et tenez-vous-y dans toute votre API :

Camel Case (createdAt, firstName) : Courant dans les écosystèmes JavaScript/TypeScript
Snake Case (created_at, first_name) : Courant dans les écosystèmes Python, Ruby et PHP

Quel que soit votre choix, documentez-le clairement et envisagez d'utiliser une couche de transformation si votre langage backend utilise une convention différente.

Codes de statut HTTP avec JSON

Des codes de statut HTTP appropriés complètent vos réponses JSON. Utilisez-les de manière cohérente :

| Code de statut | Signification | Quand l'utiliser | |-------------|---------|-------------| | 200 OK | Succès | Succès de GET, PUT, PATCH | | 201 Created | Ressource créée | Succès de POST | | 204 No Content | Suppression réussie | Succès de DELETE (aucun corps JSON) | | 400 Bad Request | Syntaxe JSON invalide | Corps de requête malformé | | 401 Unauthorized | Authentification requise | Jeton manquant ou invalide | | 403 Forbidden | Permissions insuffisantes | Authentification valide mais non autorisée | | 404 Not Found | La ressource n'existe pas | ID ou chemin invalide | | 422 Unprocessable Entity | Échec de validation | Erreurs sémantiques dans un JSON valide | | 429 Too Many Requests | Limite de débit atteinte | Le client dépasse les limites | | 500 Internal Server Error | Défaillance côté serveur | Erreurs inattendues |

Format de réponse d'erreur standard

{
  "status": "error",
  "error": {
    "code": "VALIDATION_ERROR",
    "message": "The request body contains invalid fields",
    "details": [
      {
        "field": "email",
        "message": "Must be a valid email address",
        "code": "INVALID_FORMAT"
      },
      {
        "field": "age",
        "message": "Must be a positive integer",
        "code": "OUT_OF_RANGE"
      }
    ]
  }
}

Ressources imbriquées

Représenter les relations

Les API REST doivent fréquemment représenter des ressources liées. Voici des modèles courants :

Intégré (chargement anticipé) :

{
  "order": {
    "id": 5001,
    "total": 29.99,
    "customer": {
      "id": 123,
      "name": "Alice",
      "email": "alice@example.com"
    },
    "items": [
      {
        "productId": 42,
        "name": "Widget",
        "quantity": 2,
        "price": 14.99
      }
    ]
  }
}

Référencé (chargement paresseux) -- utilisez des IDs et fournissez des points de terminaison séparés :

{
  "order": {
    "id": 5001,
    "total": 29.99,
    "customerId": 123,
    "itemIds": [101, 102]
  }
}

Règle générale : Intégrez les données liées qui sont toujours nécessaires ensemble. Référencez les données récupérées conditionnellement ou à un moment différent.

Modèles de pagination

Lorsque vous renvoyez des listes de ressources, la pagination est essentielle. Utilisez un format de pagination cohérent :

Pagination basée sur l'offset

{
  "status": "success",
  "data": [
    { "id": 1, "name": "User 1" },
    { "id": 2, "name": "User 2" }
  ],
  "pagination": {
    "page": 1,
    "perPage": 20,
    "totalItems": 156,
    "totalPages": 8,
    "links": {
      "first": "/api/users?page=1&perPage=20",
      "prev": null,
      "next": "/api/users?page=2&perPage=20",
      "last": "/api/users?page=8&perPage=20"
    }
  }
}

Pagination basée sur un curseur (recommandée pour les grands ensembles de données)

{
  "status": "success",
  "data": [
    { "id": 100, "name": "User 100" },
    { "id": 101, "name": "User 101" }
  ],
  "pagination": {
    "nextCursor": "eyJpZCI6MTAxfQ==",
    "hasMore": true
  }
}

La pagination basée sur un curseur est plus fiable pour les données en temps réel où de nouveaux enregistrements pourraient décaler les limites des pages.

JSON dans les requêtes API

Corps de requêtes POST / PUT

Acceptez le JSON avec l'en-tête Content-Type: application/json :

{
  "title": "New Blog Post",
  "content": "This is the content...",
  "tags": ["json", "rest-api"],
  "published": false
}

Mises à jour partielles avec PATCH

Utilisez PATCH pour les mises à jour partielles. N'acceptez que les champs qui doivent changer :

// PATCH /api/users/123
{
  "email": "newemail@example.com"
}

Filtrage, tri et recherche

Utilisez des paramètres de requête pour la manipulation des données, afin de garder le corps JSON propre :

GET /api/users?filter[role]=admin&sort=-createdAt&search=alice

{
  "status": "success",
  "data": [ /* filtered, sorted results */ ]
}

Limitation du débit

Incluez les informations de limitation de débit dans les en-têtes de réponse et éventuellement dans le corps JSON :

{
  "status": "error",
  "error": {
    "code": "RATE_LIMIT_EXCEEDED",
    "message": "Too many requests. Please try again later."
  },
  "meta": {
    "rateLimit": {
      "limit": 100,
      "remaining": 0,
      "resetAt": "2026-07-19T11:00:00Z"
    }
  }
}

Liste de contrôle des bonnes pratiques JSON

[ ] Utilisez un nommage de clés cohérent (camelCase ou snake_case partout)
[ ] Renvoyez des codes de statut HTTP appropriés avec chaque réponse
[ ] Incluez un format d'erreur cohérent avec des codes d'erreur lisibles par machine
[ ] Paginez les points de terminaison de listes avec un objet de pagination standardisé
[ ] Utilisez JSON Schema pour documenter et valider les structures de requêtes/réponses
[ ] Définissez Content-Type: application/json sur tous les points de terminaison JSON
[ ] Compressez les réponses JSON avec gzip ou brotli en production
[ ] Appliquez des limites maximales de taille de charge utile (par exemple, 1 Mo par défaut)
[ ] Utilisez HTTPS pour chiffrer les données JSON en transit
[ ] Structurez les détails des erreurs pour aider les clients à déboguer sans exposer les éléments internes

Valider votre JSON d'API

Faites passer vos réponses API par un validateur JSON pour détecter les erreurs de formatage avant qu'elles n'atteignent les clients. Des réponses JSON cohérentes et valides rendent votre API fiable et conviviale pour les développeurs. Utilisez notre outil Formateur et validateur JSON pour tester vos charges utiles pendant le développement.