API, formats de données

Dans cet article, explorons avec Brian Cooksey les données que nous fournissent les API, leurs formats et la façon dont HTTP rend tout cela possible. De plus en plus passionnant.

Par

Jusqu'à présent nous avons vu que le protocole HTTP est ce qui sous-tend les API et que pour utiliser ces dernières nous devons comprendre comment fonctionne HTTP. Dans cet article, nous allons explorer les données que nous fournissent les API, comment elles sont formatées et comment HTTP rend tout cela possible.

Représenter les données

Quand on partage des données, les possibilités d'affichage de l'information ne sont limitées que par notre imagination. Vous vous rappelez la pizzeria du chapitre précédent ? Comment pourraient-ils formater leur menu ? Cela pourrait être un simple texte, ou bien une liste, cela pourrait être une série de photos avec des légendes, ou simplement des photos que les clients étrangers pourraient pointer du doigt pour se faire comprendre.

Un format bien conçu est celui qui rend l'information le plus facile à comprendre pour le public visé.

Le même principe s'applique au partage de données entre ordinateurs. Un ordinateur doit transmettre les données dans un format que l'autre comprendra. Les formats les plus couramment utilisés par les API modernes sont JSON (JavaScript Object Notation) et XML (Extensible Markup Language).

JSON

Beaucoup d'API récentes ont adopté JSON comme format car il est construit à partir du langage de programmation JavaScript, que l'on trouve employé partout maintenant sur le web et qui est utilisable à la fois en front-end et en back-end. JSON est un format extrêmement simple qui comporte deux parties : les clés (keys) et les valeurs (values). Les clés représentent un attribut de l'objet que l'on décrit. Une commande de pizza peut être un objet, il a des attributs (les clés) tels que le type de pâte, la garniture, le statut de la commande. Ces attributs ont des valeurs (pâte fine, pepperoni, et en cours de livraison).

Voyons à quoi ressemblerait notre commande en JSON :

{
   "pâte": "originale",
   "garniture": ["fromage", "pepperoni", "ail"],
   "statut": "en cours de cuisson"
}

Dans l'exemple JSON ci-dessus, les clés sont les mots à gauche, ils décrivent les attributs de notre commande de pizza. Les valeurs sont à droite, ce sont les détails de notre commande.

Figure 1 - Clé et valeur en JSON

Chaque ligne peut se lire assez naturellement, la première par exemple serait "la pâte de cette pizza est dans le style original", la deuxième se lit facilement aussi si l'on sait qu'en JSON une valeur entre crochets est en fait une liste de valeurs. On peut donc lire "la garniture de cette pizza sera fromage, pepperoni et ail".

Vous pouvez également utiliser un objet comme valeur pour une clé. Complétons notre commande avec des informations sur le client :

{
  "pâte": "originale",
  "garniture": ["fromage", "pepperoni", "ail"],
  "statut": "en cours de cuisson",
  "client": {
    "nom": "Brian",
    "téléphone": "573-111-1111"
  }
}

Dans cette nouvelle version de notre commande, nous voyons qu'une clé "client" a été ajoutée. La valeur de cette clé est un autre ensemble de clés/valeurs qui nous renseigne sur le client. Pas mal, hein ? C'est un tableau associatif (associative array), rien de bien méchant, tout juste un objet imbriqué dans un autre objet.

XML

XML existe depuis 1996 et avec l'âge il s'est transformé en un format de données mature et puissant. Tout comme JSON, XML fournit des blocs nous permettant de structurer les données. Le bloc principal est appelé un noeud (node).

Voyons ce que donnerait notre commande en XML :

<commande>
    <pâte>original</pâte>
    <garnitures>
        <garniture>fromage</garniture>
        <garniture>pepperoni</garniture>
        <garniture>ail</garniture>
    <garnitures>
    <statut>en cours de cuisson</statut>
</commande>

XML commence toujours avec un noeud racine (root node), qui dans notre exemple est "commande". À l'intérieur, on trouve des noeuds "enfants". Le nom de chacun nous renseigne sur l'attribut de la commande (comme les clés en JSON) et les données à l'intérieur sont les détails (comme les valeurs en JSON)

Figure 2 - Noeud et valeur en XML

Vous pouvez aussi lire la commande en lisant le XML, la pâte de cette pizza est dans le style "originale". Remarquez comment en XML chaque item de la liste des garnitures est enveloppé dans un noeud. On voit ici que le format XML demande plus de texte que JSON.

Comment les formats de données sont utilisés en HTTP

Nous avons vus quelques formats de données, il nous faut maintenant savoir comment les utiliser en HTTP. Pour cela, nous allons appeler nos amis les headers, dont nous avons vu qu'ils étaient une liste d'informations relatives à une requête ou à une réponse. Il existe un header pour déclarer le format, c'est Content-Type.

Quand le client envoie le header Content-Type dans une requête, il indique au serveur que les données situées dans le body de la requête sont formatées d'une certaine façon. Si e client veut envoyer au serveur des données JSON, il donnera à Content-Type la valeur "application/json". À réception de la requête, et au vu de ce Content-Type, le serveur vérifiera d'abord qu'il comprend bien ce format, auquel cas il saura lire les données. De même, lorsque le serveur envoie une réponse au client, il renseignera aussi le Content-Type afin d'indiquer au client comment lire le body de la réponse.

Parfois, le client ne connait qu'un seul format. Si le serveur renvoie un autre format, le client échouera et enverra un message d'erreur. Heureusement, un deuxième header HTTP est là pour nous aider. Le client peut renseigner le header Accept pour indiquer au serveur les formats de données qu'il peut accepter. Si le client ne connaît que JSON, il peut indiquer "application/json" dans le header Accept. Le serveur enverra sa réponse en JSON. Si le serveur ne connaît pas les formats demandés par le client, il peut envoyer un message d'erreur au client pour lui indiquer que la requête ne fonctionnera pas.

Avec ces deux headers, Content-Type et Accept, le client et le serveur peuvent travailler avec les formats de données qu'ils comprennent tous les deux et dont ils ont besoin pour communiquer correctement.

Figure 3 - Headers de formats de données

Récapitulation

Dans cet article, nous avons appris que pour que deux ordinateurs communiquent entre eux, ils doivent connaître le format des données qu'ils se transmettent. Nous avons appris à connaître deux formats très communément utilisés par les API, JSON et XML. Nous avons aussi appris que le header Content-Type est utile pour spécifier le format de données envoyé dans une requête et que le header Accept spécifie le format demandé pour une réponse.

Les termes-clés que nous avons appris :

JSON : JavaScript Object Notation
Objet : une chose, ou un nom (personne, commande de pizza…)
Clé : un attribut relatif à un objet (couleur, garniture…)
Valeur : la valeur d'un attribut (bleu, pepperoni…)
Tableau associatif : un objet imbriqué
XML : Extensible Markup Language

Dans le prochain article, nous allons voir comment deux ordinateurs peuvent établir la confiance en utilisant des processus d'authentification, afin de transmettre des données sensibles ou confidentielles.

Lire l'article suivant.


Liste des articles parus :


original paru le dans Zapier.com.

Sur l'auteur : travaille chez Zapier.com, vous pouvez le suivre sur Twitter ainsi que Zapier.

Traduit avec l'aimable permission de Zapier et de l'auteur.
Copyright Zapier © 2014.