Principes de base du développement d'API REST et RESTful
Les développeurs Web parlent souvent de Principes REST et architecture de données RESTful, c’est un aspect crucial du développement moderne, mais il peut parfois être extrêmement déroutant. REST n'est pas une technologie en soi, mais plutôt une méthode de création d'API avec certains principes d'organisation. Ces principes guident les développeurs et créent un environnement plus universel pour le traitement des demandes d'API..
Dans ce post, j'aimerais expliquer les pratiques de développement RESTful à vol d'oiseau. Je veux m'attaquer la quoi plûtot que le Comment. Bien que je vais aborder ces deux domaines, cet article s'adresse à tous ceux qui s'intéressent au développement Web, mais ne peuvent tout simplement pas comprendre le concept des API REST..
REST pour les développeurs Web
L'acronyme REST signifie Transfert d'état représentatif. Cela peut sembler quelque peu déroutant et l'entrée du wiki le rend encore plus déroutant. Mais il est possible de simplifier la terminologie.
REST est juste une série de directives et styles architecturaux utilisés pour la transmission des données. Il est couramment appliqué aux applications Web, mais peut également transmettre des données à des logiciels..
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 aussi une API Web, bien qu'ils effectuent différentes tâches avec des objectifs différents..
En combinant le tout, 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 préciser les détails. Cependant, il existe certaines constantes architecturales, telles que:
- Cohérence à travers toute l'API
- Existence apatride, c'est-à-dire pas de sessions côté serveur
- Utilisation de Codes de statut HTTP le cas échéant
- Utilisation de Points de terminaison d'URL avec une hiérarchie logique
- Gestion des versions dans l'URL plutôt que dans les en-têtes HTTP
Il n’existe pas de directives trop spécifiques, telles que les spécifications HTML5 du W3C, qui pourraient prêter à confusion et créer un miasme d’incertitude autour de la terminologie REST..
En outre, la liste ci-dessus ne devrait pas être considéré comme des règles strictes, même s'ils sont vrais des API RESTful les plus modernes.
REST est un méthodologie légère ce qui le rend parfait pour les données HTTP. C’est pourquoi REST est devenu si populaire sur le Web et qu’il est largement considéré comme le meilleur choix pour le développement d’API..
Comme le dit Vinay Sahni, “une API est l'interface utilisateur d'un développeur.” Tout doit être facile à utiliser et offrir une expérience utilisateur exceptionnelle. Les API RESTful ont exactement ce but.
Points à retenir pour les API RESTful
Ces conseils sont dans le contexte des API strictement pour les applications web. Cela signifie que HTTP est une exigence, et cela signifie souvent que les données de l'API sont hébergées sur un serveur externe. Examinons le fonctionnement des API RESTful 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 d'API externe. Les données nécessaires sont ensuite transmises via HTTP. Le développeur peut ensuite afficher les données sur son site Web sans accès personnel au serveur externe (comme tirer des données Twitter).
D'une manière générale il y a quatre commandes habitué accéder aux API RESTful:
OBTENIR
pour récupérer un objetPOSTER
pour créer un nouvel objetMETTRE
pour modifier ou remplacer un objetEFFACER
pour enlever un objet
Chacune de ces méthodes devrait être passé avec l'appel de l'API pour dire au serveur quoi faire.
La grande majorité des API Web n'autorise que OBTENIR
demandes extraire les données d'un serveur externe. L’authentification est facultative, mais certainement une bonne idée lorsque vous autorisez des commandes potentiellement dommageables telles que METTRE
ou EFFACER
.
Cependant, peu d'API RESTful vont aussi loin. Pensez à Pokéapi, qui est une base de données API gratuite pour Pokémon. Il est ouvert au public avec une limitation de débit correcte (limitant les utilisateurs à un certain nombre de demandes d'API sur une période donnée), mais n'autorisant que OBTENIR
méthode d'accès aux ressources. Ceci peut être appelé familièrement un API de consommation uniquement.
Types de retour sont également importants et devraient conserver l'homogénéité pour toutes les ressources. JSON est un type de retour populaire avec des spécifications en ligne expliquant les structures de données appropriées..
Utilisation des API RESTful noms pour objets API, et verbes pour effectuer des actions sur ces objets. L'authentification peut en faire partie, la limitation de débit peut également en faire partie. Mais une API très simple peut se passer sans trop se soucier des limitations de l'utilisateur.
Accéder aux ressources de l'API
Les API publiques sont généralement accessible à partir d'adresses de sites Web directs. Ça signifie la structure de l'URL est importante, et ne devrait être utilisé que pour les requêtes API.
Certaines URL peuvent inclure un répertoire de préfixe comme / v2 /
pour une version mise à jour 2 d'une précédente API. 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 structures d'URL de base et exemples d'autres services.
Notez que le point final les données de retour vont changer radicalement basé sur la Méthode HTTP. Par exemple, OBTENIR
récupère le contenu, tandis que POSTER
crée un nouveau contenu. La demande peut pointer vers le même point de terminaison, mais le résultat peut être très différent.
En consultant les exemples en ligne, vous pourrez mieux comprendre les concepts. Nous avons déjà vu le Pokeapi, mais voici un autre 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 il n’est pas aussi compliqué que vous ne le pensez. Cela prend un compréhension des modèles de conception des API et des meilleures pratiques pour construire quelque chose de valeur réelle.
Chaque API doit connectez-vous à votre serveur renvoyer des données de quelque sorte. Pour ce faire, vous devez non seulement écrire du code, mais également formater les données de retour. Les autres exigences potentielles incluent authentification et limitation du débit, donc construire une API n'est certainement pas pour les âmes sensibles.
Mais regardons quelques principes de base de l'architecture API.
Construire des points de terminaison
Un aspect du développement des API est construction de points de terminaison. Quand créer des ressources vous voulez utiliser des noms, pas des verbes. Cela signifie que les données de l'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 préférable chaque fois que possible.
Un grand débat est singulier vs pluriel noms. Si vous réalisiez une API Twitter, vous pourriez avoir le groupe d’objets d’abord (par exemple, tweet), puis l’objet en deuxième (par exemple, ID de tweet)..
$ / tweet / 15032934882934 $ / tweets / 15032934882934
Dans ce cas, je dirais que la forme singulière est meilleure. Cela est vrai surtout quand une seule ressource est retournée. Mais il n'y a pas de réponse documentée à 100%, alors faites ce qui convient le mieux à votre projet..
Définir le type de retour
Une autre considération est type de retour. La plupart des utilisateurs Web attendent du contenu JSON, ce qui en fait 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 a beaucoup plus qui va au développement d'API, je vous recommande donc de commencer par jouer avec les API. De cette façon, vous pouvez voir comment les autres développeurs construisent leurs API, et si tout va bien vous familiariser avec les exigences typiques.
Si vous ne faites que commencer, envisagez de parcourir ces didacticiels de développement:
- Site du didacticiel de l'API REST
- Écrire une API REST simple
- Construction d'un service Web RESTful
Ressources supplémentaires
Le meilleur moyen d'apprendre à développer des applications Web consiste à pratiquer. Une théorie validée vaut toujours la peine d'être étudiée, car elle vous permet de converser avec les développeurs et de comprendre le fonctionnement.
Mais un bon point de départ pour le développement d’API est connexion à d'autres API premier. Apprenez les bases des connexions côté client et à partir de là, vous pourrez passer au développement d'API côté serveur en créant votre propre API à partir de rien..
Si tel est votre objectif, considérez les ressources suivantes pour vous aider tout au long de votre parcours..
Livres
- Livret de règles de conception d'API REST
- API Web RESTful
- Livre de recettes des services Web RESTful
- REST non perturbé: Guide de conception de l'API parfaite
Des articles
- Guide du débutant sur HTTP et REST
- Création d'une API RESTful
- Guide de nommage des ressources RESTful
- Création d'une API REST à l'aide de la pile MEAN