API, les protocoles

Dans l'article précédent, Brian Cooksey nous a fait connaître les deux côtés impliqués dans une API, le serveur et le client. Regardons maintenant de quelle manière ils communiquent entre eux.

Par

Dans l'article précédent, nous avons commencé à prendre nos marques en nous formant une image des deux côtés impliqués dans une API, le serveur et le client. Regardons maintenant comment ces deux là communiquent entre eux, en comparant d'abord le modèle humain de communication puis en le comparant à celui des ordinateurs.

Connaître les règles

Nos interactions sont guidées par des codes sociaux. Prenons l'exemple d'une conversation téléphonique. Lorsque quelqu'un parle, nous savons (en principe) que nous devons rester silencieux, lui permettre de faire des pauses, et s'il nous demande quelque chose puis reste lui-même silencieux nous savons qu'il attend une réponse et que c'est à notre tour de parler.

Les ordinateurs ont aussi ce genre de codes, mais chez eux on appelle cela des “protocoles”. Un protocole d'ordinateur est un ensemble de règles acceptées qui régissent la façon dont deux ordinateurs se parlent. En comparaison de nos standards humains, le protocole d'ordinateur est très rigide. Prenez ces deux phrases “ma couleur préférée est le bleu” et “le bleu est ma couleur préférée”, nous savons analyser chacune et constater qu'elles ont la même signification malgré l'ordre des mots. Malheureusement, les ordinateurs ne sont pas aussi intelligents.

Pour que deux ordinateurs communiquent effectivement, le serveur doit savoir exactement comment le client met en forme son message. Un peu comme quelqu'un qui vous demande votre adresse : vous lui donnerez d'abord le nom de la rue, puis le code postal et le nom de la ville. Il s'attend en outre à ce que le code postal ne comporte que des chiffres. Un niveau similaire de spécificité est requis pour faire fonctionner un protocole d'ordinateurs.

Le protocole du web

Il existe un protocole à peu près pour tout, chacun taillé sur mesure pour la tâche à exécuter. Vous en connaissez certainement quelques-uns : Bluetooth pour connecter des appareils, POP ou IMAP pour les emails.

Sur le web, le protocole principal est le Hyper-Text Transfer Protocol, mieux connu sous son petit nom HTTP. Lorsque vous tapez une adresse comme http://exemple.com dans votre navigateur, le “http” dit à votre navigateur d'utiliser les règles de HTTP lorsqu'il parle au serveur.

HTTP étant partout présent sur le web, beaucoup l'adoptent comme protocole sous-jacent à leurs API. L'utilisation d'un protocole familier a pour avantage de réduire la courbe d'apprentissage pour les développeurs, ce qui encourage l'utilisation des API. Un autre avantage est que HTTP a plusieurs caractéristiques utiles pour construire une API, comme nous le verrons plus tard. Pour l'heure, affrontons les eaux et plongeons dans le fonctionnement d'HTTP !

Les requêtes HTTP

En HTTP, la communication tourne autour d'un concept appelé le cycle requête-réponse. Le client envoie au serveur une requête pour faire quelque chose et le serveur envoie en retour une réponse au client disant si oui ou non il est en mesure de faire ce que le client lui demande.


Figure 1 - Le cycle Requête-Réponse


Pour qu'une requête soit valide, le client doit inclure quatre choses :

  1. URL (Uniform Resource Locator) (1)
  2. Méthode
  3. Liste de Headers
  4. Body

Vous vous dites peut-être que cela fait beaucoup de détails à envoyer au serveur, mais rappelez-vous que les ordinateurs doivent être précis lorsqu'ils communiquent entre eux.

URL

Les URL nous sont familières car nous les utilisons chaque jour, mais regardons leur structure. Dans HTTP, une URL est une adresse unique pour quelque chose, qui peut être une page web, une image, ou des vidéos de petits chats.

Les API étendent cette idée un peu plus loin en y incluant des noms comme consommateurs, produits, tweets... Ce faisant, les URL deviennent un moyen commode pour le client de demander au serveur avec quelles choses il veut interagir. Bien sûr, les API ne les appellent pas des “choses”, mais leur donnent leur nom technique de “ressources”.

Méthode

La méthode indique au serveur le type d'action souhaité par le client. Si les URL sont comparables à des noms, la méthode serait comparable à un verbe.

Les quatre méthodes que l'on rencontre couramment dans les API sont :

GET - Demande au serveur d'aller chercher une ressource
POST - Demande au serveur de créer une nouvelle ressource
PUT - Demande au serveur de modifier ou de mettre à jour une ressource existante
DELETE - Demande au serveur d'effacer une ressource

Prenons un exemple pour illustrer ces méthodes. Imaginons que vous puissiez communiquer par API avec une pizzeria pour passer vos commandes. Vous passez commande en envoyant une requête POST au serveur, avec les détails de votre commande, ce qui revient à lui demander de créer votre pizza. Vous vous rendez compte que vous avez demandé une pâte épaisse au lieu de fine, vous faites une requête PUT pour effectuer le changement. Pendant que vous attendez vous envoyez des requêtes GET pour savoir où en est votre commande. Après une heure d'attente, vous en avez assez et vous envoyez une requête DELETE pour annuler votre commande.

Headers

Les headers fournissent des méta-informations sur une requête. C'est une simple liste, comprenant par exemple l'heure à laquelle le client a envoyé la requête et la taille du body.

Si vous avez déjà visité un site web spécialement formaté pour votre smartphone, c'est grâce à un header HTTP appelé “User-Agent”, qui indique au serveur le type d'appareil que vous utilisez et les sites suffisamment intelligents pour le détecter vous retournent le meilleur format possible.

Les clients et serveurs utilisent un bon nombre de headers, nous y reviendrons dans les prochains articles.

Body

Le body de la requête contient les données que le client souhaite envoyer au seveur. Si nous reprenons notre exemple de pizza, le body est l'endroit où se trouvent les détails de la commande.

Une caractéristique unique du body est que le client contrôle totalement cette partie de la requête. Contrairement aux méthodes, URL et headers, où le protocole HTTP impose une structure rigide, le body permet au client d'envoyer tout ce dont il peut avoir besoin.

Ces quatre parties - URL, méthode, headers et body - forment une requête HTTP complète.

Figure 2 - La structure d'une requête HTTP


Les réponses HTTP

Lorsque le serveur reçoit la requête du client, il s'efforce d'y satisfaire et envoie une réponse. Les réponses HTTP ont une structure assez similaire à celle des requêtes, la différence principale étant qu'à la place d'une méthode et d'une URL, la réponse inclut un code de statut. À part ça, les headers et body ont le même format que dans la requête.

Les codes de statuts

Les codes de statuts sont des nombres à 3 chiffres et ils ont chacun leur signification unique. Quand il est bien utilisé dans une API, ce petit nombre peut apporter beaucoup d'informations au client. Vous avez sûrement déjà déjà rencontré ce genre de message dans vos navigations sur le net :

Figure 3 - Une page web 404 par défaut.

Le code de statut est ici 404, ce qui signifie “pas trouvé” (not found). À chaque fois qu'un client fait une requête pour une ressource qui n'existe pas, le serveur répond avec un code statut 404 pour faire savoir au client que “cette ressource n'existe pas, ne la demandez plus svp”.

Il existe une kyrielle d'autres statuts dans le protocole HTTP, dont le statut 200 (“succès ! cette requête était bonne”) et le statut 503 (“notre site ou notre API est en maintenance”). Nous en rencontrerons quelques-uns dans les articles qui viennent.

Après qu'une réponse ait été délivrée au client, le cycle requête-réponse est terminé, c'est maintenant au client d'initier de nouvelles interactions. Quant au serveur, il ne fait plus rien tant qu'il ne reçoit pas de nouvelle requête.

Figure 4 - La structure d'une réponse HTTP.


Comment les API exploitent HTTP

Jusqu'ici vous pouvez voir que HTTP est très flexible dans sa façon de mettre en relation le client et le serveur. En quoi est-ce que cela peut nous servir pour nos API ? La flexibilité d'HTTP fait que les API élaborées à partir de ce protocole fournissent aux clients beaucoup de potentialités. Nous l'avons vu avec notre commande de pizza, un simple changement dans notre méthode de requête a transformé notre demande de création d'une commande en annulation.

Cette versatilité du protocole HTTP s'étend à d'autres parties d'une requête. Certaines API exigent un header particulier, d'autres exigent des informations spécifiques à l'intérieur du body de la requête. Savoir utiliser les API repose sur la connaissance des requêtes HTTP correctes pour obtenir le résultat voulu.

Récapitulation

L'objectif de cet article était de vous donner une compréhension basique de HTTP. Le concept-clé est celui de cycle requête-réponse, que nous avons divisé ainsi :

Requête - Consiste en une URL (http://...), une méthode (GET, POST, PUT, DELETE), une liste de headers (User-Agent…) et un body (données).
Réponse - Consiste en un code de statut, une liste de headers et un body.

Tout au long de cette série d'articles, nous revisiterons ces fondamentaux en découvrant comment les API les utilisent.

Dans le prochain article, nous allons voir quel type de données les API transmettent entre client et serveur et comment HTTP rend tout cela possible.

Lire l'article suivant


Liste des articles parus :


(1) La spécification HTTP exige en fait qu'une requête ait une URI (Universal Resource Identifier), les URL en étant un sous-ensemble, tout comme les URN (Uniform Resource Name). Nous avons choisi URL parce que c'est l'acronyme que la plupart des lecteurs connaissent. Les différences subtiles entre les trois dépassent le cadre de cet article.   ↩︎


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.