L’anatomie d’un appel API

Vous avez probablement entendu le terme API (interface de programmation d’application) utilisé plus d’une fois, mais savez-vous vraiment ce qu’est une API, ce qu’elle fait et comment elle fonctionne ? Dans cet article, nous disséquons le terme et examinons les nombreux aspects d’un appel API.

Qu’est-ce qu’une API ?

Une API est un logiciel qui communique avec d’autres logiciels et fournit généralement un service. Un exemple simple est une application qui accepte des codes postaux et renvoie des informations sur la ville et la région. Le client API (l’utilisateur) demande au serveur les informations en passant le code postal en paramètre. Le serveur accepte l’appel et renvoie les données demandées.

Pour les API, le maître mot est efficacité

Imaginez que vous ayez mal à la tête. Pour arrêter votre mal de tête, vous avez besoin d’un analgésique. Vous savez que d’autres ont développé des analgésiques qui pourraient vous aider à soulager vos maux de tête, mais vous décidez plutôt de créer votre propre version du médicament. Ça n’a pas de sens. Pas vrai ? Pourquoi consacrer du temps et de l’effort à créer votre propre version d’un médicament, alors que tant d’autres l’ont déjà fait ? Sans les API, le développement logiciel serait un peu comme ça.

Le problème du partage ou de la réutilisation préoccupe le développement logiciel depuis très longtemps. Pourquoi un développeur aurait-il besoin d’écrire un nouveau programme utilitaire de code postal à chaque fois qu’il en a besoin alors que le bureau de poste en propose un gratuitement ? En utilisant une API, le développeur n’a pas à écrire le code supplémentaire, ni à mettre à jour le code à chaque fois qu’il y a un changement dans le système de code postal. C’est parce que le développeur n’a pas besoin d’écrire ou de maintenir le code qu’il peut travailler directement sur le code propre à son application.

Implémentation d’API

La manière dont un éditeur choisit de mettre en œuvre une API n’est l’affaire de personne. Absolument. Ce qui se passe au-delà de l’interface ne concerne pas le client. Lorsque vous mettez une pièce dans un distributeur de friandises, vous souciez-vous de la façon dont la machine fait tomber votre sélection ? Probablement pas, sauf si elle ne tombe pas. Les langages de codage, les bases de données et les systèmes d’exploitation utilisés par l’API n’ont pas d’importance pour le client ; c’est la beauté d’une API. Ce qui compte, c’est l’interface.

Il ne faut pas casser l’interface

Les systèmes derrière l’interface peuvent changer complètement, mais l’interface doit rester la même. Une fois qu’elle est publiée, l’éditeur veille à n’ajouter que des paramètres optionnels à une interface. Les modifications apportées aux paramètres requis d’un appel API « cassent » l’interface. Par exemple, si l’interface de l’API de code postal, qui acceptait initialement un code postal à cinq chiffres, nécessitait dorénavant six chiffres, le changement casse l’interface. En raison du changement de l’interface, toutes les applications qui utilisaient l’ancienne interface ne fonctionnent plus. Pour résoudre ce problème, l’éditeur d’API a plusieurs options :

• accepter le chiffre supplémentaire à l’aide d’un paramètre facultatif.
• accepter les deux formes, codes postaux à cinq et à six chiffres, et faire le tri en arrière-plan.
• Élargir l’API avec un nouvel appel qui accepte un code à six chiffres en laissant l’appel d’API d’origine tel quel.

L’un des outils les plus importants pour n’importe quelle API est sa documentation. La documentation est essentielle pour comprendre l’interface. L’éditeur peut fournir une documentation API statique (la documentation statique d’Uptrends API MonitorCheck) ou une documentation interactive dans un produit tel que Swagger (voir l’API d’Uptrends dans Swagger). Nous aborderons Swagger plus tard, mais les deux choses importantes à noter ici sont premièrement, vous commencez toujours par la documentation de l’API, et deuxièmement, vous la gardez à portée de main pour référence lors du codage et du dépannage des problèmes d’API.

Types d’API

Il existe toutes sortes d’API en fonction de leur objectif. Pour faire simple, mettons les API dans seulement deux groupes : les services web et les autres.

Les autres: bibliothèques, frameworks et API distantes

Aussi appelées API de code source, les développeurs utilisent ces API dans leur code source pour gérer de nombreuses tâches routinières. Par exemple, un ODBC (open database connectivity) est une API qui établit une connexion entre l’application et un système de gestion de base de données. L’API gère l’interaction entre les deux systèmes quel que soit le type de base de données, le système d’exploitation ou l’emplacement tant que la base de données est conforme OBDC (en savoir plus sur les différents types d’API).

Les API telles que les bibliothèques API et les frameworks rendent les logiciels plus robustes pour plusieurs raisons. Elles :

• encouragent la réutilisation du code
• accélèrent le processus de développement
• permettent le partage de ressources ; par exemple, une application sur votre téléphone a accès aux services de localisation à l’aide d’une API

Les API ont révolutionné le web et l’Internet des objets.

Les API de services web

Les services web sont des API qui exécutent des tâches via Internet. Presque toutes les actions que vous effectuez en ligne utilisent un ou plusieurs services web :

• vérifier une réservation
• traiter une transaction par carte de crédit
• extraire des informations produit du catalogue d’un fournisseur
• télécharger des images depuis ou vers des réseaux sociaux
• obtenir des itinéraires via une application de navigation

La liste est sans fin et comprend de nombreuses fonctionnalités auxquelles nous ne pensons jamais. Par exemple, les mises à jour de vos appareils intelligents, le système de navigation de votre voiture accédant à Google Maps pour obtenir et donner les conditions de circulation actuelles, et votre téléviseur intelligent accédant à l’API d’un service de streaming comme Netflix.

Dissection d’un appel API de service web

Le plus souvent, les services web utilisent le style architectural REST API (Representational State Transfer Application Program Interface). Un service web conforme au style de l’API REST est appelé « RESTful ». REST ne spécifie ni la langue ni le système d’exploitation, il définit simplement les principes de conception auxquels une API doit se conformer pour se déclarer RESTful. En savoir plus sur les API RESTful. Les exemples qui suivent utilisent le style architectural RESTful.

Les API RESTful utilisent HTTP

Les API RESTful communiquent en utilisant HTTP/HTTPS tout comme les navigateurs web, et un appel à une API ressemble beaucoup à l’URL pour accéder à une page web. Par exemple, l’appel à l’API d’Uptrends pour obtenir la liste complète des points de contrôle et leurs adresses IP est :

https://api.uptrends.com/v4/Checkpoint

L’URL permettant d’afficher les mêmes données en tant que page web est :

https://www.uptrends.com/checkpoints

Ce dernier fournit une page web tandis que le premier renvoie un résultat XML ou un résultat JavaScript Object Notation (JSON).

Les verbes HTTP

Les Méthodes HTTP ou les verbes définissent l’action voulue. Même s’il existe davantage de méthodes de requête HTTP, nous nous concentrons ici sur cinq des méthodes les plus utilisées.

• GET La méthode de requête GET récupère quelque chose à partir d’une ressource. Par exemple, dans notre exemple Checkpoint ci-dessus, l’appel API aboutit à une liste. Mais il peut également demander un fichier, un statut, un script ou toute autre ressource numérique.
• POST La méthode de requête POST envoie des données (et des fichiers) à la ressource. Un POST peut demander à la ressource de faire de nombreuses choses, par exemple, mettre à jour un panier, créer un compte, faire une réservation ou publier sur des réseaux sociaux.
• PUT La méthode de requête PUT est comme la méthode POST en ce qu’elle demande que la ressource soit mise à jour ou créée. Cependant, renvoyer de nouveau (à l’identique) une requête POST ne fait rien du tout, c’est-à-dire qu’elle est idempotente. Par exemple, avec un POST, il est possible que la requête est envoyée deux fois lorsqu’un utilisateur clique une deuxième fois sur un bouton d’envoi. En utilisant PUT, vous évitez les commandes clients en double. Un PUT nécessite que la requête spécifie une URI (uniform resource identifier) qui identifie de manière unique la ressource devant être mise à jour. Si la ressource existe déjà, PUT effectue les modifications, et si la ressource n’existe pas, PUT crée l’objet avec cet URI.
• PATCH Un PATCH est une modification partielle ou une mise à jour d’une ressource. Avec un PUT ou un POST, vous envoyez la totalité de la ressource à chaque fois, mais avec un PATCH, vous pouvez n’envoyer que les mises à jour.
• DELETE Comme vous pouvez l’imaginer, une requête DELETE supprime une ressource entière. Le serveur décide de la manière dont il gère la demande DELETE et pourrait en fait ne pas supprimer la ressource.

Requête et réponse HTTP

Comme vous le savez probablement déjà, une requête HTTP se produit lorsque le client demande quelque chose au serveur, et ensuite la réponse est renvoyée par l’hôte. La réponse peut inclure des données ou simplement un code de résultat. La requête et la réponse utilisent le format suivant :

• Ligne de requête La ligne de requête du client spécifie le verbe HTTP, l’URI de la requête et la version HTTP. La réponse a également une « ligne de requête » (ou ligne de statut) mais cette ligne contient la version HTTP et le code de réponse.
• En-têtes HTTP utilise des en-têtes pour transmettre des informations supplémentaires à l’aide de paires nom/valeur. La requête peut contenir de nombreuses lignes d’en-tête, telles que l’hôte, la date et l’heure, les informations de connexion, les informations de type de contenu, la taille du contenu et les paramètres de cache.
• Ligne vide Une ligne vide signifie la fin des en-têtes et le début du corps du message.
• Corps du message Les requêtes GET et DELETE n’ont pas besoin du corps de message facultatif, mais pour les autres requêtes, le corps du message contient les données (le cas échéant) dont le serveur ou le client a besoin.

Regardons quelques exemples :

Exemple de requête

La requête suivante concerne l’API Points de contrôle d’Uptrends. Comme vous pouvez le voir dans le code ci-dessous, vous avez d’abord la ligne de requête avec le verbe, l’URI et la version du protocole. La deuxième ligne, Host dans l’en-tête, donne le nom de domaine du serveur. La troisième ligne, Accept dans l’en-tête, indique à l’API de répondre avec du code JSON. La quatrième ligne est l’en-tête d’autorisation qui donne les détails d’authentification de base codés.

GET /v4/checkpoint/202 HTTP1.1
Host: api.uptrends.com
Accept: application/json
Authorization: Basic bWjIxOEBNd2ljajb206MRnNjkzNAGFlbEB1cHRyZW5kcy5==

Exemple de réponse

La première ligne de la réponse API est la version du protocole et le code de résultat. Les en-têtes de la réponse indiquent au navigateur des informations sur la réponse, telles que la durée pendant laquelle le contenu peut rester dans le cache, le type de contenu, la date/heure et la taille du contenu. Après les en-têtes se trouve une ligne vide suivie du corps du message. Le corps du message contient du code JSON (comme indiqué dans la requête), mais ça peut également être du XML.

HTTP/1.1 200 OK
access-control-expose-headers: Request-Context
cache-control: no-cache
content-length: 63823
content-type: application/json
date: Thu, 03 Sep 2020 20:41:47 GMT
expires: -1
pragma: no-cache
referrer-policy: same-origin
request-context: appId=cid-v1:fa5a4436-5708-4a19-90fb-5e2623304195

{
"Data": {
"Id": 202,
"Type": "Checkpoint",
"Attributes": {
"CheckpointName": "Aalsmeer",
"Code": "AAL1",
"Ipv4Addresses": [
"213.214.121.213",
"185.113.196.214"
],
"IpV6Addresses": [
{
"IpAddress": "2a02:2858:201:4e::5",
"IsNative": true
},
{
"IpAddress": "2a02:2858:401:1::214",
"IsNative": true
}
],
"IsPrimaryCheckpoint": true,
"SupportsIpv6": true,
"HasHighAvailability": false
},
"Links": {
"Self": "/Checkpoint/221"
}
},
"Links": {
"Self": "/Checkpoint/221"
}
}

L’exemple ci-dessus demande des informations sur un point de contrôle spécifique. Un appel précédent utilisant un URI différent a récupéré l’ID de point de contrôle utilisé dans cet exemple. Certains appels API sont indépendants, mais de nombreux appels font partie d’un échange d’API plus large.

Outils de test des appels d’API

Il existe de nombreux outils gratuits et payants disponibles qui vous permettent d’envoyer et de tester des appels API. Deux outils en vogue sont cURL et Swagger UI. Un autre outil prisé dont nous ne discuterons pas ici est Postman. Postman a un plan gratuit si vous souhaitez explorer davantage l’outil.

cURL

L’outil le plus utilisé est probablement cURL. Le «c» fait référence à la ligne de commande et la partie URL représente le localisateur de ressources universel. L’outil permet d’envoyer et de recevoir des données à partir de la ligne de commande, et HTTP n’est que l’un des nombreux protocoles pris en charge.

cURL est probablement déjà installé sur votre ordinateur (si vous utilisez Unix ou un Mac, l’outil est préinstallé). Pour savoir si cURL est installé sur votre ordinateur Windows, vous pouvez effectuer un test rapide.

• Ouvrez une fenêtre de commande (vous pouvez taper « cmd » dans la zone de recherche pour trouver cmd.exe).
  
• À l’invite de commande, tapez curl https://www.uptrends.com.
• Appuyez sur Entrée.

Le résultat (voir la figure ci-dessous) est le code HTML du site web d’Uptrends. En utilisant la notation cURL, vous pouvez ajouter des en-têtes à vos requêtes API. Pour en savoir plus sur l’utilisation de cURL et le télécharger, allez sur le site officiel. Vous pouvez également télécharger le livre électronique gratuit, Everything curl.

Tester les appels d’API à l’aide de Swagger

Swagger est un outil de documentation visuelle qui permet aux développeurs et aux utilisateurs d’interagir directement avec votre API sans avoir besoin d’un environnement dédié. Si l’API que vous envisagez d’utiliser a une spécification OpenAPI, tout va bien. Uptrends a un outil de configuration basé sur la spécification OpenAPI à utiliser avec la version quatre de l’API, si vous avez un compte Uptrends actif.

Comment utiliser la spécification OpenAPI d’Uptrends ?

Si vous disposez d’une connexion Uptrends, vous pouvez utiliser la page Uptrends dédiée à Swagger pour interagir avec l’API Uptrends. Dans la section suivante, nous allons vous montrer deux choses : comment exécuter un appel API à l’aide de Swagger et comment obtenir votre nom d’utilisateur et votre mot de passe API.

La première chose à faire est d’obtenir vos informations d’identification API.

1. Allez à la page de la Documentation Swagger de l’API Uptrends v4.
2. Faites défiler jusqu’à Register et cliquez pour développer. Vous remarquerez de nombreux autres appels en cours de route, mais ne vous y arrêtez pas pour l’instant. Vous pourrez les explorer plus tard.
   
3. Cliquez sur la barre verte pour afficher la documentation de l’appel API.
4. Cliquez sur Try it out pour accéder au bouton Execute .
   
5. Cliquez sur Execute.
6. À l’aide de vos identifiants de connexion Uptrends, remplissez le formulaire de connexion dans la fenêtre pop-up.
   
7. Cliquez sur Sign in.
8. Notez les valeurs de UserName et Password renvoyées dans le corps de la réponse. Vous en aurez besoin pour accéder à l’API.
   
9. Remontez vers le haut de la page web Swagger.
10. Cliquez sur le bouton vert Authorize.
11. Utilisez le nom d’utilisateur et le mot de passe renvoyés dans le corps de la réponse précédemment pour renseigner les champs (il vous suffit de remplir la section supérieure).
    
12. Cliquez sur Authorize.
13. Cliquez sur Close.

Si vous n’êtes pas connecté, vous aurez des erreurs d’authentification lors de vos tentatives d’appel API. Essayez les différents appels API (il est probablement préférable de s’en tenir aux requêtes GET). Remarquez la syntaxe cURL utilisée pour effectuer l’appel (voir la figure ci-dessous). Swagger fournit vos informations d’identification avec une valeur d’en-tête d’autorisation codée.

Encodage d’en-tête d’autorisation

Si vous êtes un utilisateur de l’API Uptrends et que vous utilisez d’autres moyens (tels que des scripts) pour interagir avec l’API, vous aurez peut-être à encoder vos informations d’identification d’API. Pour encoder vos informations d’identification, utilisez l’encodage base64 sur le nom d’utilisateur et le mot de passe séparés par deux points.

Par exemple, le nom d’utilisateur et le mot de passe

7341223ce90947cda53a66f67481908a:ipbI6+6wUXxlCYSTBUaCuuUyjTQYfNjM

devient

NzM0MTIyM2NlOTA5NDdjZGE1M2E2NmY2NzQ4MTkwOGE6aXBiSTYrNndVWHhsQ1lTVEJVYUN1dVV5alRRWWZOak0=

avec encodage base64 à l’aide d’un outil en ligne gratuit.

Conclusion

J’espère que vous avez maintenant une meilleure compréhension des services web et de leur fonctionnement. N’hésitez pas à continuer d’explorer l’API Uptrends à l’aide de Swagger, et vous remarquerez que ces informations sont également utiles lors de la configuration de la Surveillance d’API multi-étapes. Si vous avez des questions sur l’API, nous vous encourageons à explorer notre Base de connaissances ou consultez l’un de nos héros Support.