Qu'est-ce qu'une API — les règles convenues pour l'échange entre programmes, et JSON

Cet article traite des API.

Une API, ce sont les règles convenues entre programmes pour échanger des données.

Tu vas voir les trois éléments d'un appel et le JSON, le format de texte qui revient.

• Ce que « appeler une API » envoie réellement, et où
• Les trois éléments d'un appel — URL, méthode, réponse
• Comment lire les clés et les valeurs du JSON qui revient
• Le code de statut qui indique la réussite ou l'échec, et quoi faire ensuite selon le numéro

« Appeler une API », c'est envoyer une requête à une URL définie et recevoir une réponse

Les données météo ne sont pas détenues par ton propre programme, mais par le serveur d'un service externe.

Une API appelée avec des requêtes et des réponses HTTP est une API Web (Web API), et chacune des URL qu'elle accepte est un endpoint.

Un service externe peut être le fournisseur, et le serveur de my-app aussi.

Et un même écran n'appelle pas forcément un seul endpoint.

Trois allers-retours de requête et de réponse ont lieu avant que la page n'apparaisse.

Le navigateur ne se connecte directement qu'au serveur de my-app.

Le même serveur est le fournisseur vu du navigateur, et l'appelant vu de l'API météo.

Appeler une API, c'est envoyer et recevoir

Appeler une API, c'est envoyer une requête à une URL définie et recevoir la réponse qui revient.

Chacune de ces URL est un endpoint ; l'appelant peut être le navigateur comme ton propre serveur, et le fournisseur n'est pas forcément un service externe.

Les trois éléments d'un appel — URL, méthode, réponse

Les guides et la documentation ne donnent que trois choses.

Où l'envoyer (l'URL), ce que tu veux faire (la méthode) et ce qui revient (la réponse).

La première, l'URL, se partage en deux rôles de part et d'autre du ?.

Ce qui suit le ? est un paramètre (query parameter : une condition des données voulues, ajoutée à la fin de l'URL sous la forme nom=valeur), aussi appelé paramètre de requête.

Le deuxième élément est la méthode (HTTP method : un mot défini comme GET ou POST, qui indique ce que la requête veut faire).

Tu l'écris en début de ligne, et elle change le comportement même quand tu envoies à la même URL.

GET ne change pas les données de l'autre côté, alors que POST les change au moment de l'envoi.

Les guides l'écrivent sous la forme d'une méthode suivie d'une URL.

Les lignes qui commencent par # sont des explications, et la ligne juste en dessous est la manière d'appeler.

# Récupérer la météo. La méthode d'abord, l'URL ensuite (paramètres à la fin)
GET https://api.example.com/weather?city=tokyo

# Enregistrer une réservation. Même URL, méthode différente, comportement différent
POST https://example.com/reservations

Le document qui rassemble cette manière d'appeler et la forme de la réponse qui revient est la documentation de l'API (API reference).

Quand un guide dit « consulte la documentation de l'API », c'est là que tu cherches les trois éléments.

Avant d'envoyer, tu ne décides que deux choses

Avant d'envoyer, tu ne décides que deux choses : où l'envoyer et ce que tu veux faire.

Où l'envoyer, c'est l'URL, dont la partie avant le ? est l'endpoint ; ce que tu veux faire, c'est la méthode. Le troisième élément, la réponse, est le seul que tu ne décides pas : tu lis ce qui revient.

Le JSON est un format de texte qui écrit les données par paires de clé et de valeur

Le « JSON qui est revenu » du guide, c'est le corps de la réponse.

JSON (JavaScript Object Notation : un format fait uniquement de texte, qui écrit les données par paires de clé et de valeur) est le format le plus courant pour le corps des API Web.

Le JSON que renvoie l'API météo a cette forme.

{
  "city": "Tokyo",
  "temp": 23.5,
  "rain": false,
  "forecast": [
    { "day": "mon", "high": 25 },
    { "day": "tue", "high": 22 }
  ]
}

Ce qui est aligné, ce sont des paires clé et valeur (key / value : la clé est le nom donné à une valeur, et la valeur le contenu désigné par ce nom).

Dans "temp": 23.5, temp est la clé et 23.5 la valeur ; le caractère : relie la clé et la valeur, et le caractère , sépare les paires.

Les paires s'alignent dans des { }, et une valeur peut elle-même être un [ ] ou un { }.

La quatrième valeur est un tableau (array : plusieurs valeurs alignées dans l'ordre à l'intérieur de [ ]), et chaque élément est de nouveau entouré de { }.

Les { } et les [ ] s'imbriquent sur autant de niveaux que l'on veut.

Pour extraire un élément d'un tableau, tu le désignes par un numéro comme [0], et la numérotation commence à 0, pas à 1.

Les valeurs qui ne sont ni [ ] ni { } s'écrivent de trois façons, que l'on distingue selon la présence des " ".

Tel qu'il est reçu, le corps est une seule longue chaîne : désigner une clé ne suffit pas à en extraire la valeur.

Dans les livres d'initiation, tu le convertis d'abord en une forme dont les clés se lisent, avec une seule ligne comme JSON.parse, puis tu désignes une valeur par le nom de la clé, comme data.city.

Seule la dernière ligne comporte une clé volontairement mal orthographiée, à un caractère près.

Une faute d'orthographe ne déclenche pas d'erreur : quand tu obtiens undefined, commence par comparer l'orthographe avec le JSON.

Le nom contient JavaScript, mais tous les langages savent le lire et l'écrire, d'où son usage pour les réponses d'API.

Le JSON n'est qu'une suite de paires nom-contenu

Le JSON n'est rien d'autre qu'une suite de caractères alignant des paires formées d'un nom et de son contenu.

Le nom est la clé, le contenu la valeur ; tel qu'il est reçu, c'est une seule longue chaîne, donc tu le convertis en une forme lisible par clé avant d'en extraire les valeurs.

Une réponse n'est pas toujours une réussite — le code de statut décide de la suite

L'API météo tourne en dehors de ton propre programme : un appel peut échouer.

C'est pourquoi une réponse n'arrive pas avec le corps seul.

Regarde ce qui revient en séparant les parties.

Les trois chiffres en tête forment le code de statut (status code : le numéro qui indique la réussite ou l'échec, et de quelle sorte).

Regarde d'abord le numéro, et ne lis les clés du corps qu'en cas de réussite.

On n'apprend pas les trois chiffres par cœur : c'est le premier chiffre qui décide de la suite.

Même avec la même API météo, le numéro qui revient change selon ce que tu as envoyé et l'état du fournisseur.

Outre le 404, un 500 revient quand une anomalie survient du côté du fournisseur.

404 n'est pas seulement le numéro du « page inexistante » : avec une API, il revient aussi quand aucune donnée ne correspond aux conditions des paramètres.

Si tu appelles comme indiqué et qu'un 404 revient, compare l'orthographe et les paramètres avec la documentation de l'API.

Parmi les numéros qui commencent par 4, le 401 est celui du cas où rien n'indique qui est l'appelant, ou bien ce qui est indiqué n'est pas correct.

La clé d'API est ce que tu joins à la requête pour l'indiquer.

Lire le numéro avant le corps

Quand une réponse revient, lis le numéro avant le corps.

S'il commence par 2, le corps contient la clé voulue ; s'il commence par 4, corrige l'URL et les conditions envoyées ; s'il commence par 5, attends un peu et rappelle.