Comprendre et utiliser les API REST

Il y a de fortes chances que vous rencontriez le terme "API REST" si vous avez pensé à obtenir des données d'une autre source sur Internet, comme Twitter ou Github. Mais qu'est-ce qu'une API REST ? Que peut-il faire pour vous? Comment l'utilisez-vous?

Dans cet article, vous apprendrez tout ce que vous devez savoir sur les API REST pour pouvoir lire les documentations des API et les utiliser efficacement.

Qu'est-ce qu'une API REST

Disons que vous essayez de trouver des vidéos sur Batman sur Youtube. Vous ouvrez Youtube, tapez "Batman" dans un champ de recherche, appuyez sur Entrée et vous voyez une liste de vidéos sur Batman. Une API REST fonctionne de manière similaire. Vous recherchez quelque chose et vous obtenez une liste de résultats du service que vous demandez.

Une API est une interface de programmation d'application. C'est un ensemble de règles qui permettent aux programmes de communiquer entre eux. Le développeur crée l'API sur le serveur et permet au client de lui parler.

REST détermine à quoi ressemble l'API. Il signifie « transfert d'État représentatif ». Il s'agit d'un ensemble de règles que les développeurs suivent lorsqu'ils créent leur API. L'une de ces règles stipule que vous devriez pouvoir obtenir une donnée (appelée ressource) lorsque vous créez un lien vers une URL spécifique.

Chaque URL s'appelle une requête tandis que les données qui vous sont renvoyées s'appellent une réponse .

L'anatomie d'une demande

Il est important de savoir qu'une demande est composée de quatre éléments :

1. Le point final
2. La méthode
3. Les en-têtes
4. Les données (ou corps)

Le point de terminaison (ou route) est l'URL que vous demandez. Il suit cette structure :

 root-endpoint/ ? root-endpoint/ ? root-endpoint/ ?

Le point de terminaison racine est le point de départ de l'API à partir de laquelle vous demandez. Le point de terminaison racine de l'API de Github est https://api.github.com tandis que l'API de Twitter du point de terminaison racine est https://api.twitter.com .

Le chemin détermine la ressource que vous demandez. Considérez-le comme un répondeur automatique qui vous demande d'appuyer sur 1 pour un service, appuyez sur 2 pour un autre service, 3 pour encore un autre service et ainsi de suite.

Vous pouvez accéder à des chemins tout comme vous pouvez créer des liens vers des parties d'un site Web. Par exemple, pour obtenir une liste de tous les articles marqués sous "JavaScript" sur Smashing Magazine, vous accédez à https://www.smashingmagazine.com/tag/javascript/ . https://www.smashingmagazine.com/ est le point de terminaison racine et /tag/javascript est le chemin.

Pour comprendre quels chemins sont à votre disposition, vous devez consulter la documentation de l'API. Par exemple, supposons que vous souhaitiez obtenir une liste des référentiels d'un certain utilisateur via l'API de Github. La documentation vous indique d'utiliser le chemin suivant pour le faire :

 /users/:username/repos

Tout deux-points ( : ) sur un chemin indique une variable. Vous devez remplacer ces valeurs par les valeurs réelles du moment où vous envoyez votre demande. Dans ce cas, vous devez remplacer :username par le nom d'utilisateur réel de l'utilisateur que vous recherchez. Si je cherche mon compte Github, je remplacerai :username par zellwk .

Le point de terminaison pour obtenir une liste de mes dépôts sur Github est le suivant :

 https://api.github.com/users/zellwk/repos

La dernière partie d'un point de terminaison correspond aux paramètres de requête . Techniquement, les paramètres de requête ne font pas partie de l'architecture REST, mais vous verrez de nombreuses API les utiliser. Donc, pour vous aider à comprendre parfaitement comment lire et utiliser les API, nous allons également en parler. Les paramètres de requête vous permettent de modifier votre requête avec des paires clé-valeur. Ils commencent toujours par un point d'interrogation ( ? ). Chaque paire de paramètres est ensuite séparée par une esperluette ( & ), comme ceci :

 ?query1=value1&query2=value2

Lorsque vous essayez d'obtenir une liste des dépôts d'un utilisateur sur Github, vous ajoutez trois paramètres possibles à votre requête pour modifier les résultats qui vous sont donnés :

Si vous souhaitez obtenir une liste des référentiels vers lesquels j'ai poussé récemment, vous pouvez définir sort sur push .

 https://api.github.com/users/zellwk/repos?sort=pushed

Comment savoir si ce point de terminaison fonctionne ? Eh bien, il est temps d'essayer !

Tester les points de terminaison avec curl

Vous pouvez envoyer une requête avec n'importe quel langage de programmation. Les utilisateurs de JavaScript peuvent utiliser des méthodes telles que l'API Fetch et la méthode Ajax de jQuery ; Les utilisateurs de Ruby peuvent utiliser la classe Net ::HTTP de Ruby, les utilisateurs de Python peuvent utiliser les requêtes Python ; etc.

Pour cet article, nous utiliserons l'utilitaire de ligne de commande appelé cURL. Nous utilisons cURL car les documentations d'API sont normalement écrites en référence à cURL. Si vous comprenez comment utiliser cURL, vous n'aurez aucun problème à comprendre les documentations de l'API. Ensuite, vous pouvez facilement effectuer des demandes avec votre langue préférée.

Avant de continuer, vous devez vous assurer que cURL est installé sur votre machine. Ouvrez votre terminal et tapez curl -version . Cette commande vérifie la version de cURL que vous avez installée sur votre système.

 curl --version

Si vous n'avez pas installé cURL, vous obtiendrez une erreur "commande introuvable". Si vous obtenez cette erreur, vous devrez installer curl avant de continuer.

Pour utiliser cURL, vous tapez curl , suivi du point de terminaison que vous demandez. Par exemple, pour obtenir le point de terminaison racine de Github, vous saisissez ce qui suit :

 curl https://api.github.com

Une fois que vous avez appuyé sur Entrée, vous devriez obtenir une réponse de Github qui ressemble à ceci :

Pour obtenir une liste des référentiels d'un utilisateur, vous modifiez le point de terminaison sur le chemin correct, comme ce dont nous avons discuté ci-dessus. Pour obtenir une liste de mes référentiels, vous pouvez utiliser cette commande :

 curl https://api.github.com/users/zellwk/repos

Si vous souhaitez inclure des paramètres de requête avec cURL, assurez-vous d'ajouter une barre oblique inverse ( \ ) avant le ? et = caractères. C'est parce que ? et = sont des caractères spéciaux dans la ligne de commande. Vous devez utiliser \ devant eux pour que la ligne de commande les interprète comme des caractères normaux :

 curl https://api.github.com/users/zellwk/repos\?sort\=pushed

Essayez d'utiliser l'une ou l'autre des commandes et effectuez une requête ! Vous obtiendrez une réponse similaire à ce que vous avez vu avec le root-endpont de Github (mais avec beaucoup plus de données).

JSON

JSON (JavaScript Object Notation) un format courant pour envoyer et demander des données via une API REST. La réponse que Github vous renvoie est également au format JSON.

Un objet JSON ressemble à un objet JavaScript. Dans JSON, chaque propriété et valeur doit être entourée de guillemets doubles, comme ceci :

 { "property1": "value1", "property2": "value2", "property3": "value3" }

Retour à l'anatomie d'une demande

Vous avez appris qu'une demande se compose de quatre parties.

1. Le point final
2. La méthode
3. Les en-têtes
4. Les données (ou corps)

Passons en revue le reste de ce qui constitue une demande.

La méthode

La méthode est le type de requête que vous envoyez au serveur. Vous pouvez choisir parmi ces cinq types ci-dessous :

• GET
• POST
• PUT
• PATCH
• DELETE

Ces méthodes donnent un sens à la requête que vous faites. Ils sont utilisés pour effectuer quatre actions possibles : Create , Read , Update à jour et Delete (CRUD).

L'API vous permet de savoir quelle méthode de requête utiliser pour chaque requête. Par exemple, pour obtenir la liste des référentiels d'un utilisateur, vous avez besoin d'une requête GET :

Une requête GET est requise pour obtenir une liste de référentiels d'un utilisateur. Pour créer un nouveau dépôt Github, vous avez besoin d'une requête POST :

Vous pouvez définir la méthode de requête dans cURL en écrivant -X ou --request , suivi de la méthode de requête. Cette commande ci-dessous tente de créer un référentiel via cURL :

 curl -X POST https://api.github.com/user/repos

Essayez d'exécuter cette requête. Vous obtiendrez une réponse vous indiquant que l'authentification est requise. (Plus d'informations sur l'authentification plus tard).

 { "message": "Requires authentication", "documentation_url": "https://developer.github.com/v3" }

Les en-têtes

Les en-têtes sont utilisés pour fournir des informations au client et au serveur. Il peut être utilisé à de nombreuses fins, telles que l'authentification et la fourniture d'informations sur le contenu du corps. Vous pouvez trouver une liste des en-têtes valides sur la référence des en-têtes HTTP de MDN.

Les en-têtes HTTP sont des paires propriété-valeur séparées par deux-points. L'exemple ci-dessous montre un en-tête qui indique au serveur d'attendre du contenu JSON.

 "Content-Type: application/json". Missing the opening ".

Vous pouvez envoyer des en-têtes HTTP avec curl via l'option -H ou --header . Pour envoyer l'en-tête ci-dessus à l'API de Github, vous utilisez cette commande :

 curl -H "Content-Type: application/json" https://api.github.com

(Remarque : l'en-tête Content-Type n'est pas obligatoire pour que l'API de Github fonctionne. Ceci n'est qu'un exemple pour illustrer comment utiliser un en-tête avec cURL).

Pour afficher les en-têtes que vous avez envoyés, vous pouvez utiliser l'option -v ou --verbose lorsque vous envoyez la requête, comme ceci :

 curl -H "Content-Type: application/json" https://api.github.com -v 

Ici, * fait référence à des informations supplémentaires fournies par cURL. > fait référence aux en-têtes de requête et < fait référence aux en-têtes de réponse.

Les données (ou « corps »)

Les données (parfois appelées « corps » ou « message ») contiennent des informations que vous souhaitez envoyer au serveur. Cette option n'est utilisée qu'avec les requêtes POST , PUT , PATCH ou DELETE .

Pour envoyer des données via cURL, vous pouvez utiliser l'option -d ou --data :

 curl -X POST <URL> -d property1=value1

Pour envoyer plusieurs champs de données, vous pouvez créer plusieurs options -d :

 curl -X POST <URL> -d property1=value1 -d property2=value2

Si cela a du sens, vous pouvez diviser votre requête en plusieurs lignes \ pour en faciliter la lecture :

 curl -X POST <URL> \ -d property1=value1 \ -d property2=value2

Si vous savez comment faire tourner un serveur, vous pouvez créer une API et tester vos propres données. Si vous ne savez pas, mais que vous vous sentez assez courageux pour essayer, vous pouvez suivre cet article pour apprendre à créer un serveur avec Node, Express et MongoDB.

Si vous ne voulez pas faire tourner votre serveur, vous pouvez aller sur Requestbin.com ( c'est gratuit ! ) et cliquer sur « créer un point de terminaison ». Vous recevrez une URL que vous pourrez utiliser pour tester les demandes, comme https://requestb.in/1ix963n1 montré dans l'image ci-dessous.

Assurez-vous de créer votre propre corbeille de requêtes si vous souhaitez tester votre requête. Les bacs de requête ne restent ouverts que 48 heures après sa création. Au moment où vous lirez cet article, la corbeille que j'ai créée ci-dessus aura disparu depuis longtemps.

Maintenant, essayez d'envoyer des données à votre corbeille de requêtes, puis actualisez la page Web de votre corbeille. Vous verrez des données, comme ceci :

 curl -X POST https://requestb.in/1ix963n1 \ -d property1=value1 \ -d property2=value2 

Par défaut, cURL envoie les données comme si elles étaient envoyées via des "champs de formulaire" sur une page. Si vous souhaitez envoyer des données JSON, vous devrez définir le Content-Type sur application/json , et vous devrez formater vos données en tant qu'objet JSON, comme ceci :

 curl -X POST https://requestb.in/1ix963n1 \ -H "Content-Type: application/json" \ -d '{ "property1":"value1", "property2":"value2" }' 

Et c'est (presque !) tout ce que vous devez savoir sur la structure d'une requête.

Maintenant, souvenez-vous que lorsque vous avez essayé d'envoyer une requête POST via l'API de Github, vous avez reçu un message indiquant « Nécessite une authentification » ? Eh bien, c'est parce que vous n'êtes pas autorisé à effectuer la requête POST !

Authentification

Vous ne permettrez à personne d'accéder à votre compte bancaire sans votre permission, n'est-ce pas ? Dans le même ordre d'idées, les développeurs ont mis en place des mesures pour s'assurer que vous n'effectuez des actions que lorsque vous y êtes autorisé. Cela empêche les autres de se faire passer pour vous.

Étant donné que les requêtes POST , PUT , PATCH et DELETE modifient la base de données, les développeurs les placent presque toujours derrière un mur d'authentification. Dans certains cas, une requête GET nécessite également une authentification (comme lorsque vous accédez à votre compte bancaire pour vérifier votre solde actuel, par exemple).

Sur le web, il existe deux manières principales de vous authentifier :

1. Avec un nom d'utilisateur et un mot de passe (également appelé authentification de base)
2. Avec un jeton secret

La méthode du jeton secret inclut oAuth, qui vous permet de vous authentifier auprès des réseaux sociaux tels que Github, Google, Twitter, Facebook, etc.

Pour cet article, vous apprendrez uniquement à utiliser l'authentification de base avec un nom d'utilisateur et un mot de passe. Si vous souhaitez vous authentifier avec oAuth, je vous suggère de lire "Ce que vous devez savoir sur OAuth2 et la connexion avec Facebook" par Zack Grossbart.

Pour effectuer une authentification de base avec cURL, vous pouvez utiliser l'option -u , suivie de votre nom d'utilisateur et de votre mot de passe, comme ceci :

 curl -x POST -u "username:password" https://api.github.com/user/repos

Essayez de vous authentifier avec votre nom d'utilisateur et votre mot de passe dans la demande ci-dessus. Une fois que vous avez réussi l'authentification, vous verrez la réponse passer de "Nécessite une authentification" à "Problèmes d'analyse de JSON".

En effet, vous n'avez pas encore fourni de données (qui sont requises par toutes les requêtes POST , PUT , PATCH et DELETE ) au serveur.

Avec les connaissances que vous avez acquises jusqu'à présent, vous devriez pouvoir modifier le code ci-dessus pour créer un référentiel Github via votre cURL. Je vous laisse essayer vous-même !

Parlons maintenant des codes d'état HTTP et des messages d'erreur.

Codes d'état HTTP et messages d'erreur

Certains des messages que vous avez reçus précédemment, comme « Nécessite une authentification » et « Problèmes d'analyse de JSON » sont des messages d'erreur. Ils n'apparaissent que lorsque quelque chose ne va pas avec votre demande. Les codes d'état HTTP vous permettent d'indiquer rapidement l'état de la réponse. La gamme de 100+ à 500+. En général, les nombres suivent les règles suivantes :

1. 200+ signifie que la requête a réussi .
2. 300+ signifie que la requête est redirigée vers une autre URL
3. 400+ signifie qu'une erreur provenant du client s'est produite
4. 500+ signifie qu'une erreur provenant du serveur s'est produite

Vous pouvez déboguer le statut d'une réponse avec l'option verbose ( -v ou --verbose ) ou l'option head ( -I ou --head ).

Par exemple, si vous essayez d'ajouter -I à une requête POST sans fournir votre nom d'utilisateur et votre mot de passe, vous obtiendrez un code d'état 401 (non autorisé) :

Si votre demande est invalide parce que vos données sont erronées ou manquantes, vous obtenez généralement un code de statut 400 (Bad Request).

Pour obtenir plus d'informations sur les codes d'état HTTP spécifiques, vous pouvez consulter la référence d'état HTTP de MDN.

Versions d'API

Les développeurs mettent à jour leurs API de temps en temps. Parfois, l'API peut tellement changer que le développeur décide de mettre à niveau son API vers une autre version. Si cela se produit et que votre application tombe en panne, c'est généralement parce que vous avez écrit du code pour une ancienne API, mais que votre requête pointe vers la nouvelle API.

Vous pouvez demander une version d'API spécifique de deux manières. La manière dont vous choisissez dépend de la façon dont l'API est écrite.

Ces deux manières sont :

1. Directement dans le terminal
2. Dans un en-tête de requête

Twitter, par exemple, utilise la première méthode. Au moment de la rédaction, l'API de Twitter est à la version 1.1, ce qui est évident à travers son point de terminaison :

 https://api.twitter.com/1.1/account/settings.json

Github, en revanche, utilise la deuxième méthode. Au moment de la rédaction de cet article, l'API de Github est à la version 3 et vous pouvez spécifier la version avec un en-tête Accept :

 curl https://api.github.com -H Accept:application/vnd.github.v3+json

Emballer

Dans cet article, vous avez appris ce qu'est une API REST et comment utiliser cURL pour effectuer une requête avec les méthodes GET , POST , PUT , PATCH et DELETE . De plus, vous avez également appris comment authentifier vos requêtes avec l'option -u et ce que signifient les statuts HTTP.

J'espère que cet article vous a aidé à en apprendre suffisamment sur les API REST et que vous pourrez les utiliser couramment lors de la création de vos applications. N'hésitez pas à passer sur mon blog ou à laisser vos commentaires ci-dessous si vous avez des questions.