Blog
Point de vue

Une introduction complète à la spécification JSON:API

Ce guide explore JSON:API : concepts, structure et fonctionnalités avancées.

Louis Dupont

Louis Dupont

5 June 2025

Une introduction complète à la spécification JSON:API

REST (Representational State Transfer) fournit un style architectural fondamental pour la création de services web. Cependant, il laisse de nombreux aspects du formatage des requêtes et des réponses non définis. Cette ambiguïté peut entraîner des incohérences, une augmentation des frais de développement et une courbe d'apprentissage plus raide pour les consommateurs d'API. Entrez JSON:API, une spécification qui fournit une approche normalisée et basée sur des conventions pour la création d'API en JSON.

Ce guide complet propose une plongée en profondeur dans la spécification JSON:API, explorant ses concepts de base, sa structure et ses fonctionnalités puissantes. Nous allons disséquer ses mécanismes pour récupérer, créer, mettre à jour et supprimer des ressources, gérer les relations, gérer les erreurs et optimiser le transfert de données, vous dotant des connaissances nécessaires pour concevoir et consommer des API robustes et efficaces.

💡
Vous voulez un excellent outil de test d'API qui génère de belles documents d'API ?

Vous voulez une plateforme intégrée, tout-en-un, pour que votre équipe de développeurs travaille ensemble avec une productivité maximale ?

Apidog répond à toutes vos demandes et remplace Postman à un prix beaucoup plus abordable !
button

Pourquoi JSON:API ? Explication :

Avant de plonger dans les subtilités techniques, il est crucial de comprendre les problèmes que JSON:API vise à résoudre. Sans convention partagée, les développeurs d'API passent souvent beaucoup de temps à débattre :

JSON:API y répond en définissant un format clair et cohérent pour les requêtes et les réponses. Cette normalisation offre plusieurs avantages clés :

Concepts de base : les éléments constitutifs d'un document JSON:API

Au cœur de JSON:API se trouve le concept de ressources. Une ressource est un enregistrement individuel d'un type particulier, tel qu'un "article", un "utilisateur" ou un "produit". Chaque document JSON:API, qu'il s'agisse d'une requête ou d'une réponse, adhère à une structure spécifique.

La structure du document : membres de niveau supérieur

Un document JSON:API est un objet JSON qui doit contenir au moins l'un des membres de niveau supérieur suivants :

De plus, un document peut contenir ces membres de niveau supérieur :

Objets ressources : représenter vos données

Un objet ressource est la pierre angulaire de JSON:API et doit contenir :

Un objet ressource peut également contenir :

Exemple d'objet ressource :JSON

{
  "type": "articles",
  "id": "1",
  "attributes": {
    "title": "JSON:API Unveiled",
    "body": "A deep dive into the specification...",
    "created_at": "2025-05-15T10:00:00Z",
    "updated_at": "2025-05-16T14:30:00Z"
  },
  "relationships": {
    "author": {
      "links": {
        "self": "/articles/1/relationships/author",
        "related": "/articles/1/author"
      },
      "data": { "type": "users", "id": "42" }
    },
    "comments": {
      "links": {
        "self": "/articles/1/relationships/comments",
        "related": "/articles/1/comments"
      },
      "data": [
        { "type": "comments", "id": "5" },
        { "type": "comments", "id": "12" }
      ]
    }
  },
  "links": {
    "self": "/articles/1"
  }
}

Objets identifiants de ressource

Les objets identifiants de ressource sont des représentations minimales d'une ressource, contenant uniquement type et id. Ils sont utilisés dans les objets de relation pour établir un lien vers d'autres ressources sans intégrer l'objet ressource complet.

Exemple d'objet identifiant de ressource :JSON

{ "type": "users", "id": "42" }

Objets Liens

Les objets liens fournissent des URL pour naviguer dans l'API. Les membres de liens courants incluent :

Un lien peut être représenté comme :

Exemple d'objet Liens (dans une relation) :JSON

"links": {
  "self": "http://example.com/articles/1/relationships/author",
  "related": "http://example.com/articles/1/author"
}

Objets Meta

Les objets Meta permettent l'inclusion de méta-informations non standard. Il peut s'agir de paires clé-valeur arbitraires. Par exemple, un objet meta pourrait inclure des informations sur le droit d'auteur ou des horodatages liés aux données.

Exemple d'objet Meta :JSON

"meta": {
  "copyright": "Copyright 2025 Example Corp.",
  "authors": ["John Doe"]
}

Négociation de contenu : parler le bon langage

JSON:API définit son propre type de média : application/vnd.api+json.

Les serveurs peuvent prendre en charge d'autres types de médias aux côtés de application/vnd.api+json grâce à la négociation de contenu standard.

Récupération de données : récupération de ressources et de collections

JSON:API fournit des mécanismes robustes permettant aux clients de récupérer des données précisément selon leurs besoins.

Récupération de ressources individuelles

Pour récupérer une seule ressource, un client envoie une requête GET à un point de terminaison représentant cette ressource.

Requête :

GET /articles/1

Accept : application/vnd.api+json

Réponse réussie (200 OK) :JSON

{
  "links": {
    "self": "/articles/1"
  },
  "data": {
    "type": "articles",
    "id": "1",
    "attributes": {
      "title": "JSON:API Rocks!"
    }
    // ... other attributes and relationships
  }
}

Si la ressource n'existe pas, le serveur devrait renvoyer un 404 Not Found. Si un lien de ressource connexe un-à-un est récupéré et que la relation est vide, les données principales seront null.

Récupération de collections de ressources

Pour récupérer une collection de ressources, un client envoie une requête GET à un point de terminaison représentant cette collection.

Requête :

GET /articles

Accept : application/vnd.api+json

Réponse réussie (200 OK) :JSON

{
  "links": {
    "self": "/articles",
    "next": "/articles?page[offset]=10",
    "last": "/articles?page[offset]=50"
  },
  "data": [
    {
      "type": "articles",
      "id": "1",
      "attributes": { "title": "Article 1" }
      // ...
    },
    {
      "type": "articles",
      "id": "2",
      "attributes": { "title": "Article 2" }
      // ...
    }
    // ... more articles
  ]
}

Si la collection est vide, le membre data sera un tableau vide [].

Relations : connexion des ressources

Les relations sont une partie fondamentale de la plupart des modèles de données. JSON:API fournit un moyen clair de les définir et d'interagir avec elles.

Représentation des relations

Les relations sont définies dans l'objet relationships d'une ressource. Chaque entrée de l'objet relationships représente une relation distincte (par exemple, "auteur", "commentaires").

Un objet de relation doit contenir au moins l'un des éléments suivants :

Exemple de relations "auteur" (un-à-un) et "commentaires" (un-à-plusieurs) :JSON

"relationships": {
  "author": {
    "links": {
      "self": "/articles/1/relationships/author",
      "related": "/articles/1/author"
    },
    "data": { "type": "users", "id": "42" }
  },
  "comments": {
    "links": {
      "self": "/articles/1/relationships/comments",
      "related": "/articles/1/comments"
    },
    "data": [
      { "type": "comments", "id": "5" },
      { "type": "comments", "id": "12" }
    ]
  }
}

Récupération des relations

Les clients peuvent récupérer des informations sur une relation elle-même ou sur les ressources connexes à l'aide des liens fournis.

Récupération de la liaison de relation (lien self) :

GET /articles/1/relationships/comments

Accept : application/vnd.api+json

Cela renvoie une collection d'objets identifiants de ressource pour les commentaires liés à l'article "1".

Récupération des ressources connexes (lien related) :

GET /articles/1/comments

Accept : application/vnd.api+json

Cela renvoie une collection d'objets de ressource de commentaire complets liés à l'article "1".

Optimisation de la récupération des données

JSON:API offre plusieurs fonctionnalités pour optimiser la façon dont les données sont récupérées, minimisant la bande passante et améliorant les performances côté client.

Documents composés : réduction des requêtes HTTP avec include

Pour éviter plusieurs allers-retours vers le serveur pour récupérer les ressources connexes, JSON:API permet aux clients de demander que les ressources connexes soient incluses dans la réponse principale à l'aide du paramètre de requête include. Le serveur chargera ensuite ces ressources dans le tableau included de niveau supérieur.

Requête pour récupérer un article et inclure son auteur et ses commentaires :

GET /articles/1?include=author,comments

Accept : application/vnd.api+json

Réponse (200 OK) :JSON

{
  "data": {
    "type": "articles",
    "id": "1",
    "attributes": { "title": "..." },
    "relationships": {
      "author": {
        "data": { "type": "users", "id": "42" }
      },
      "comments": {
        "data": [
          { "type": "comments", "id": "5" },
          { "type": "comments", "id": "12" }
        ]
      }
    }
  },
  "included": [
    {
      "type": "users",
      "id": "42",
      "attributes": { "name": "John Doe" }
    },
    {
      "type": "comments",
      "id": "5",
      "attributes": { "body": "Great article!" }
    },
    {
      "type": "comments",
      "id": "12",
      "attributes": { "body": "Very informative." }
    }
  ]
}

Ensembles de champs clairsemés : récupération uniquement des champs nécessaires

Les clients peuvent demander que seuls des champs spécifiques (attributs et relations) soient renvoyés pour les ressources d'un type donné à l'aide du paramètre de requête fields[TYPE]. Cela réduit la taille de la charge utile.

Requête pour récupérer des articles, mais uniquement leur titre et leur relation d'auteur :

GET /articles?fields[articles]=title,author

Accept : application/vnd.api+json

Réponse (200 OK) :JSON

{
  "data": [
    {
      "type": "articles",
      "id": "1",
      "attributes": {
        "title": "Article 1"
      },
      "relationships": {
        "author": {
          "data": { "type": "users", "id": "42" }
        }
      }
    }
    // ... other articles with only title and author
  ]
}

Tri

Les clients peuvent demander que les données principales soient triées à l'aide du paramètre de requête sort.

Requête pour récupérer des articles triés par date de création (décroissante), puis par titre (croissant) :

GET /articles?sort=-created_at,title

Accept : application/vnd.api+json

Pagination

JSON:API prend en charge diverses stratégies de pagination. La spécification définit comment les liens de pagination (first, prev, next, last) doivent apparaître dans l'objet links de niveau supérieur. La stratégie de pagination réelle (par exemple, basée sur les pages, basée sur les décalages, basée sur les curseurs) est déterminée par le serveur à l'aide de paramètres de requête tels que page[number], page[size], page[offset], page[limit] ou page[cursor].

Exemple de liens de pagination basés sur les pages :JSON

"links": {
  "self": "/articles?page[number]=2&page[size]=10",
  "first": "/articles?page[number]=1&page[size]=10",
  "prev": "/articles?page[number]=1&page[size]=10",
  "next": "/articles?page[number]=3&page[size]=10",
  "last": "/articles?page[number]=5&page[size]=10"
}

Les clients doivent utiliser ces liens fournis plutôt que de construire leurs propres URL de pagination.

Filtrage

La spécification réserve le paramètre de requête filter pour le filtrage des données. Cependant, elle n'impose pas de stratégie de filtrage spécifique. Les serveurs peuvent implémenter n'importe quelle stratégie, telle que filter[attribute]=value ou un filtrage plus complexe basé sur des expressions.

Exemple (recommandé par JSON:API, mais non obligatoire) :

GET /comments?filter[post]=1 (Obtenir les commentaires pour le message avec l'ID 1)

GET /comments?filter[post]=1,2&filter[author]=12 (Obtenir les commentaires pour les messages 1 ou 2, par l'auteur 12)

Les clients doivent consulter la documentation de l'API pour comprendre ses capacités de filtrage spécifiques.

Modification des données : création, mise à jour et suppression de ressources

JSON:API définit des protocoles clairs pour les opérations de manipulation de données.

Création de ressources

Pour créer une ressource, un client envoie une requête POST à une URL représentant une collection de ressources. Le corps de la requête doit contenir un seul objet ressource avec type et, éventuellement, attributes et relationships. Le client ne doit pas fournir d'id pour la nouvelle ressource (sauf si les ID générés par le client sont pris en charge et activés).

Requête :

POST /articles

Accept : application/vnd.api+json

Content-Type : application/vnd.api+jsonJSON

{
  "data": {
    "type": "articles",
    "attributes": {
      "title": "New Article Title",
      "body": "Content of the new article."
    },
    "relationships": {
      "author": {
        "data": { "type": "users", "id": "42" }
      }
    }
  }
}

Réponses réussies :

Si une tentative est faite pour créer une ressource avec un ID généré par le client qui existe déjà, et que le serveur ne prend pas en charge la mise à jour via POST, il doit renvoyer 409 Conflict.

Mise à jour des ressources

Les ressources sont mises à jour à l'aide de la méthode HTTP PATCH. La requête doit inclure l'id de la ressource à mettre à jour. Le corps de la requête contient un objet ressource avec type, id et les attributes et/ou relationships à mettre à jour.

Requête pour mettre à jour le titre d'un article et l'une de ses relations :

PATCH /articles/1

Accept : application/vnd.api+json

Content-Type : application/vnd.api+jsonJSON

{
  "data": {
    "type": "articles",
    "id": "1",
    "attributes": {
      "title": "Updated Article Title"
    },
    "relationships": {
      "tags": {
        "data": [
          { "type": "tags", "id": "3" },
          { "type": "tags", "id": "4" }
        ]
      }
    }
  }
}

Points clés pour les mises à jour :

Réponses réussies :

Si la ressource à mettre à jour n'existe pas, le serveur doit renvoyer 404 Not Found.

Mise à jour des relations directement

JSON:API fournit des moyens spécifiques de gérer les relations sans affecter les attributs de la ressource principale.

{
  "data": { "type": "users", "id": "24" } // Assign new author or null to clear
}

{
  "data": [
    { "type": "comments", "id": "101" },
    { "type": "comments", "id": "102" }
  ]
}

{
  "data": [
    { "type":

Explore more

Fathom-R1-14B : Modèle de raisonnement IA avancé d'Inde

Fathom-R1-14B : Modèle de raisonnement IA avancé d'Inde

L'IA en expansion rapide. Fathom-R1-14B (14,8 milliards de paramètres) excelle en raisonnement mathématique et général, conçu par Fractal AI Research.

5 June 2025

Mistral Code : L'assistant de codage le plus personnalisable basé sur l'IA pour les entreprises

Mistral Code : L'assistant de codage le plus personnalisable basé sur l'IA pour les entreprises

Découvrez Mistral Code, l'IA d'aide au code la plus personnalisable pour les entreprises.

5 June 2025

Comment Claude Code transforme le codage de l'IA en 2025

Comment Claude Code transforme le codage de l'IA en 2025

Découvrez Claude Code en 2025 : codage IA révolutionné. Fonctionnalités, démo, et pourquoi il gagne du terrain après Windsurf d'Anthropic. Indispensable !

5 June 2025

Pratiquez le Design-first d'API dans Apidog

Découvrez une manière plus simple de créer et utiliser des API

S'inscrire gratuitementTélécharger