API call : qu'est-ce que c'est et comment faire ?

Les API permettent à différentes applications web de communiquer entre elles et d'échanger des informations ou des fonctionnalités. Elles sont définies comme un ensemble de codes qui est implémenté par des appels de fonction. C'est là que les API calls entrent en jeu.

Souvent négligé, l'API call est un aspect crucial à comprendre, car il constitue la base des fonctionnalités détaillées de l'API. Tout comme nous avons besoin d'un interrupteur sur la télévision ou d'un clavier pour fournir des entrées à l'ordinateur portable, les appels d'API sont nécessaires pour appeler des données d'une autre application/logiciel.

Créés et échangés en grande quantité, les API Calls sont l'aspect le plus important de l'écosystème API.

Autrement dit, les appels d'API sont le mécanisme qui permet à une application cliente de demander à une application ou à un serveur d'effectuer une opération spécifique.

L'API définit :

• Les opérations que l'application cliente peut demander.
• Les informations requises par l'application cliente pour répondre à la demande.
• Les informations que le service renverra à l'application cliente en réponse à la demande.

Les étapes d'un API call sont les suivantes :

• Le programme soumet une demande d'informations à l'API. Cette demande peut être une simple recherche, une tentative de connexion, etc.
• L'API examine la validité de la demande et transmet l'appel à un programme externe.
• L'API reçoit une réponse du programme externe, puis renvoie les données au programme demandeur.

Exemples : prenons le processus de connexion à une application. La première fois qu'un utilisateur ouvre une application, celle-ci lui demande une adresse électronique/un nom d'utilisateur et un mot de passe. L'envoi de ces informations implique un appel d'API. La réponse du serveur est d'autoriser l'accès, après avoir validé les informations de connexion de l'utilisateur.

Un autre exemple d'API call est la vérification de la disponibilité d'un site web pour les réservations. Un utilisateur qui souhaite réserver une chambre d'hôtel pour un certain nombre de jours doit indiquer ces jours dans le champ et cliquer sur « Envoyer ». L'API examine la demande, recueille des informations sur la disponibilité pour ces dates et renvoie ces informations à l'utilisateur. Il s'agit d'un processus d'interrogation simple, et l'API rend la communication entre les systèmes, transparente.

Même le partage de photos sur Facebook ou Instagram implique l'utilisation d'une API de base. La demande consiste à télécharger la photo, et l'API confirme au serveur de Facebook qu'il s'agit d'une demande valide. Une fois que le serveur a autorisé la demande, le téléchargement a lieu. De cette façon, les appels d'API sont des gardiens.

En bref, les API calls permettent de récupérer à peu près n'importe quel type d'information par le biais d'applications et de recherches sur le web, pour autant que la demande soit validée par la passerelle API.

Examiner la documentation de l'API

Avant d'effectuer un API call, il est absolument important de consulter la documentation de l'API. C'est une source de référence qui décrit en détail le fonctionnement d'une interface de programmation d'applications et guide les utilisateurs et les développeurs dans son utilisation. La documentation de l'API précise les paramètres que les appels d'API comportent et fournit des explications sur les appels et l'envoi de requêtes à l'aide d'une interface de programmation d'applications.

Rechercher l'URI du serveur

La première chose que les utilisateurs doivent faire pour passer un appel API est de connaître l'URI du serveur dont ils souhaitent obtenir les données. Le terme URI désigne un élément qui permet d'identifier une ressource sur internet. Il s'agit essentiellement de l'équivalent numérique d'une adresse personnelle. En recherchant l'URI du serveur, les utilisateurs ont une idée précise de l'endroit où ils vont envoyer leur demande.

Il faut savoir que la plupart des API ont des points de terminaison divers qui peuvent être utilisés pour obtenir différents types de données. Ces derniers exécutent une fonction spécifique en tâche de fond et prennent un ou plusieurs arguments pour renvoyer les données adéquates. Par exemple, dans le cas d'un utilisateur qui souhaite diffuser des tweets publics en temps réel en utilisant ensuite le point de terminaison de flux filtré de Twitter, le chemin de base, commun à tous les terminaux, est https://api.twitter.com et le point de terminaison du flux filtré est /2/tweets/search/stream. Ce dernier peut être ajouté à la fin du chemin de base ou répertorié dans la demande.

Faire une requête HTTP

Après avoir trouvé l'URI du serveur, les utilisateurs doivent savoir comment effectuer une requête. Pour formuler des requêtes à une API, ils doivent passer des appels HTTP. HTTP désigne un ensemble de méthodes de requête qui précisent l'action à réaliser sur les données indiquées. Ces méthodes sont appelées des verbes HTTP. Ceux-ci doivent être inclus dans un appel d'API. Les verbes HTTP les plus utilisés sont :

• GET pour récupérer une ressource ;
• POST pour créer une nouvelle ressource ;
• PUT pour modifier ou mettre à jour une ressource existante ;
• PATCH pour modifier des ressources ;
• DELETE pour supprimer une ressource.

Par exemple, un client qui utilise l'API de la station de carburant alternatif de NREL et souhaite consulter une liste des stations de carburant alternatif les plus proches de Denver dans le Colorado va effectuer la requête suivante :

• GET https://developer.nrel.gov/api/alt-fuel-stations/v1/nearest.json?api_key=XXXXXXXXX&location=Denver+CO

De son côté, le serveur va rechercher une liste de stations de carburant alternatives à Denver dans la base de données avant de renvoyer une copie de cette ressource au format JSON ou XML.

Voici un aperçu de la récupération des données dans le format JSON :

Ajouter un entête

• Ensuite, il faut inclure un entête dans la requête. Cet élément informe l'API de la demande d'un utilisateur et de la réponse qu'il attend. Le but de l'inclusion d'un entête est que l'API comprenne ce que le client demande et lui apporter une réponse facile à comprendre et à utiliser. Dans le cas d'un appel d'API, trois entêtes sont couramment :User-agent : il permet à l'API d'identifier l'application ou le logiciel utilisé par l'utilisateur qui fait la requête HTTP. Cet entête correspond généralement au nom du navigateur web ou du moteur de recherche.
• Content-type : il permet d'indiquer le type de ressource que la requête contient. Sans cet entête, il est difficile pour l'API de comprendre la demande du client ou de la décoder. Dans ce cas, ce dernier ne peut pas obtenir de réponse à sa requête.
• Accept : il permet de spécifier dans quel format le client souhaite recevoir les données que l'API va lui renvoyer. En cas d'absence de cet entête, l'API risque de retourner les données demandées dans un format qui ne correspond pas à celui que le client demande. C'est pourquoi elle doit toujours être incluse dans un appel d'API afin que le client puisse obtenir la réponse exacte qu'il souhaite.

Obtenir une clé API ou un jeton d'accès

Pour se connecter à une interface de programmation d'applications, une clé API ou un jeton d'accès est nécessaire. Ces deux identifiants uniques permettent d'authentifier les appels API. Ils se composent d'une série de lettres et de chiffres qui identifient l'application cliente à l'origine de la demande. La clé API et le jeton d'accès sont utilisés pour accorder ou refuser les demandes selon les autorisations d'accès des utilisateurs. Ils servent également à suivre le nombre de demandes effectuées à des fins statistiques, d'utilisation et de facturation.

Recevoir une réponse de l'API

Enfin, il ne reste plus qu'à attendre une réponse de l'API. Les utilisateurs vont recevoir un code d'état indiquant si le traitement de la demande a abouti ou non.

Les codes d'état sont divisés en cinq catégories :

• 1xx : Informatif - Communique des informations au niveau du protocole de transfert.
• 2xx : Success - Indique que la demande du client a été acceptée avec succès.
• 3xx : Redirection - Indique que le client doit effectuer une action supplémentaire afin de compléter sa demande.
• 4xx : Client Error - Cette catégorie de codes indique que l'erreur vient du client.
• 5xx : Server Error – Ici, le serveur est responsable de ces codes d'état d'erreur.

Les codes les plus courants sont les codes 2XX et les codes 4XX. Les codes 2XX, qui correspondent aux codes de réussite, précisent que le serveur a reçu la demande du client et l'a traitée avec succès. À l'inverse, les codes 4XX signalent la présence d'une erreur dans la requête. Cela signifie que la demande est formulée de manière incorrecte ou que les données demandées n'existent pas. Dans ces cas-là, le code d'état explique le problème afin qu'il puisse être corrigé.

Les codes d'état les plus courants sont :

• 200 OK : la demande a réussi ;
• 201 Created : la ressource a été créée sur le serveur ;
• 202 Accepted : la demande a été reçue, mais est toujours en cours de traitement ;
• 204 No Content : la requête a été traitée avec succès, mais aucun contenu n'est renvoyé ;
• 400 Bad Request : la demande contient des données incorrectes ;
• 401 Unauthorized : le client n'est pas autorisé à effectuer cette demande ;
• 403 Forbidden : la demande est correcte, mais ne peut pas être traitée, car le client ne dispose probablement pas des autorisations requises ;
• 404 Not found : les informations demandées n'existent pas. Ce code d'état est le plus connu des internautes qui le voient apparaître quand ils essayent d'accéder à une page web qui n'existe pas ou plus.

Pour aller plus loin, téléchargez ce guide gratuit sur HTML et CSS et découvrez les définitions, les différences et les éléments de code de base de ces deux langages de programmation pour gérer votre site web.