Les bases de REST et du développement de l'API RESTful

Les développeurs Web parlent souvent des principes REST et de l'architecture des données RESTful, car c'est un aspect crucial du développement moderne, mais parfois cela peut être incroyablement déroutant. REST n'est pas une technologie en soi, mais plutôt une méthode de création d'API avec certains principes organisationnels . Ces principes sont destinés à guider les développeurs et à créer un environnement plus universel pour le traitement des demandes d'API.

Dans ce post, je voudrais expliquer les pratiques de développement RESTful à partir d'une vue d'oiseau. Je veux aborder le quoi plutôt que le comment . Bien que j'aborderai les deux domaines, ce post est destiné à tous ceux qui s'intéressent au développement web, mais qui ne peuvent tout simplement pas comprendre le concept des API REST.

REST pour les développeurs Web

L'acronyme REST signifie Representational State Transfer . Cela peut sembler quelque peu déroutant, et l'entrée wiki rend le son encore plus déroutant. Mais il est possible de simplifier la terminologie.

REST est juste une série de lignes directrices et de styles architecturaux utilisés pour la transmission de données . Il est généralement appliqué aux applications Web, mais peut également transmettre des données au logiciel.

L'API acronyme signifie Application Programming Interface, qui sont des méthodes de connexion avec d'autres bibliothèques ou applications . Windows a plusieurs API, et Twitter a également une API Web, bien qu'ils effectuent différentes tâches avec des objectifs différents.

En combinant tout cela, les API RESTful sont des API qui suivent l'architecture REST.

Quelle est exactement l'architecture REST?

C'est là qu'il est difficile de fixer des détails. Cependant, il existe des constantes architecturales, telles que:

• Cohérence sur l'ensemble de l'API
• Existence sans état, c'est-à-dire pas de sessions côté serveur
• Utilisation des codes d'état HTTP, le cas échéant
• Utilisation de points de terminaison d'URL avec une hiérarchie logique
• Versionnement dans l'URL plutôt que dans les en-têtes HTTP

Il n'y a pas de directives trop spécifiques comme la spécification HTML5 du W3C qui pourrait conduire à la confusion, et un miasme d'incertitude autour de la terminologie REST.

En outre, la liste ci-dessus ne doit pas être considérée comme une règle stricte, même si elle est vraie pour la plupart des API RESTful modernes.

REST est une méthodologie légère qui le rend parfait pour les données HTTP. C'est pourquoi REST est devenu si populaire sur le Web, et pourquoi il est largement considéré comme le meilleur choix pour le développement de l'API.

Comme le dit Vinay Sahni, «une API est l'interface utilisateur d'un développeur». Tout devrait être facile à utiliser et offrir une expérience utilisateur exceptionnelle. Les API RESTful ont pour but de faire exactement cela.

Key Takeaways pour les API RESTful

Ces conseils sont dans le contexte des API strictement pour les applications Web . Cela signifie que le protocole HTTP est requis et que les données de l'API sont souvent hébergées sur un serveur externe . Examinons comment les API RESTful fonctionnent du côté de l'utilisateur de l'API.

L'utilisateur de l'API est le développeur Web qui peut créer un script qui se connecte à un serveur API externe, puis les données nécessaires sont transmises via HTTP. Le développeur peut alors afficher des données sur son site web sans avoir d'accès personnel au serveur externe (comme tirer des données Twitter).

En règle générale, quatre commandes sont utilisées pour accéder aux API RESTful :

1. GET pour récupérer un objet
2. POST pour créer un nouvel objet
3. PUT pour modifier ou remplacer un objet
4. DELETE pour supprimer un objet

Chacune de ces méthodes devrait être passée avec l'appel d'API pour dire au serveur quoi faire.

La grande majorité des API Web autorise uniquement les requêtes GET à extraire des données d'un serveur externe. L'authentification est facultative, mais certainement une bonne idée en permettant des commandes potentiellement dommageables comme PUT ou DELETE .

Cependant, peu d'API RESTful vont aussi loin. Considérez Pokéapi qui est une base de données API Pokémon gratuite. Il est ouvert au public avec une limitation de débit décente (en limitant les utilisateurs à un certain nombre de demandes d'API sur une période donnée), mais ne permet que la méthode GET pour accéder aux ressources. Ceci peut être familièrement appelé une API de consommation seulement .

Les types de retour sont également importants et doivent conserver une homogénéité pour toutes les ressources. JSON est un type de retour populaire avec des spécifications en ligne qui expliquent les structures de données appropriées.

Les API RESTful utilisent des noms pour les objets API et des verbes pour effectuer des actions sur ces objets. L'authentification peut faire partie de cela, la limitation de débit peut également faire partie de cela. Mais une API très simple peut s'en sortir sans trop se soucier des limitations de l'utilisateur.

Accès aux ressources de l'API

Les API publiques sont généralement accessibles à partir d'adresses de sites Web directes . Cela signifie que la structure de l'URL est importante et ne doit être utilisée que pour les demandes d'API.

Certaines URL peuvent inclure un répertoire de préfixe comme /v2/ pour une version 2 mise à jour d'une API précédente. Ceci est courant pour les développeurs qui ne veulent pas déprécier leur API 1.x, mais veulent quand même offrir la structure la plus récente.

J'ai vraiment apprécié ce post couvrant les structures d'URL de base et les exemples d'autres services.

Notez que les données de retour du point de terminaison changeront considérablement en fonction de la méthode HTTP . Par exemple, GET récupère du contenu, tandis que POST crée un nouveau contenu. La requête pourrait pointer vers le même point de terminaison, mais le résultat pourrait être très différent.

Regarder des exemples en ligne peut vous aider à comprendre les concepts plus clairement. Nous avons déjà vu le Pokeapi, mais voici d'autres exemples d'API du monde réel à parcourir:

• API Reddit
• API GitHub
• API Flickr
• API Pinterest

Construire votre propre API

Le processus de construction de votre propre API ne doit pas être pris à la légère, mais ce n'est pas aussi compliqué que vous pourriez le penser. Il faut bien comprendre les modèles de conception d'API et les meilleures pratiques pour créer quelque chose de valeur réelle.

Chaque API doit se connecter à votre serveur pour renvoyer des données quelconques. Non seulement vous devez écrire du code pour le faire, mais vous devez également formater les données de retour. D'autres exigences potentielles incluent l' authentification et la limitation de débit, de sorte que la création d'une API n'est certainement pas pour les faibles d'esprit.

Mais jetons un coup d'œil à quelques principes de base de l'architecture de l'API.

Construire des points d'extrémité

Un aspect du développement de l'API est la construction de points de terminaison . Lorsque vous créez des ressources, vous voulez utiliser des noms, pas des verbes. Cela signifie que les données API doivent renvoyer une personne, un lieu ou une chose, le plus souvent c'est une chose avec des attributs spécifiques (par exemple un tweet et toutes ses métadonnées).

Il peut être difficile d'apprendre à nommer les noms, mais c'est un aspect crucial du développement de l'API. La simplification est la meilleure possible.

Un grand débat est singulier contre les noms pluriels . Si vous étiez en train de créer une API Twitter, vous pourriez avoir le groupe d'objets en premier (c.-à-d. Tweet), puis le deuxième objet (ie tweet ID).

 $ / tweet / 15032934882934 $ / tweets / 15032934882934 

Dans ce cas, je dirais que la forme singulière semble mieux. Cela est particulièrement vrai lorsqu'une seule ressource est renvoyée. Mais il n'y a pas de réponse correcte à 100%, alors faites ce qui convient le mieux à votre projet.

Définir le type de retour

Une autre considération est les données de type de retour . La plupart des internautes attendent du contenu JSON, c'est probablement la meilleure option. XML est un autre choix si vous voulez offrir les deux. Cependant, JSON est le type de retour d'API fondamental parmi les développeurs Web.

Il y en a beaucoup plus dans le développement de l'API, donc je recommande de commencer par jouer avec les API. De cette façon, vous pouvez voir comment les autres développeurs construisent leurs API, et espérons que vous vous familiariserez avec les exigences typiques.

Si vous commencez tout juste, s'il vous plaît envisager d'écraser ces tutoriels dev:

• Site du tutoriel de l'API REST
• Ecriture d'une API REST simple
• Construire un service Web RESTful

Autres ressources

La meilleure façon d'apprendre le développement d'applications Web est de pratiquer. La théorie admise vaut toujours la peine d'être étudiée, car elle vous permet de converser avec les développeurs et de comprendre comment les choses fonctionnent.

Mais un bon point de départ pour le développement de l'API est d'abord de se connecter à d'autres API . Apprenez les bases des connexions côté client, et à partir de là, vous pouvez passer au développement d'API côté serveur en créant votre propre API à partir de zéro.

Si tel est votre objectif, veuillez considérer les ressources suivantes pour vous aider dans votre voyage.

Livres

• REST API Règles de conception
• API Web RESTful
• Livre de recettes des services Web RESTful
• REST non perturbé: un guide pour concevoir l'API parfaite

Des articles

• Guide du débutant sur HTTP et REST
• Créer une API RESTful
• Guide de nommage des ressources RESTful
• Création d'une API REST à l'aide de la pile MEAN