Meilleures pratiques d'API REST – Serveur d’impression
De nombreux géants tels que Facebook, Google, Github, Netflix, Amazon et Twitter ont leurs propres API REST (complètes) auxquelles vous pouvez accéder pour obtenir ou même écrire des données.
Mais pourquoi tout le besoin de repos?
Est-ce si bon et pourquoi est-il si répandu?
Ce n’est sûrement pas le seul moyen de transmettre des messages?
Quelle est la différence entre REST et HTTP?
Eh bien, il s'avère REST est assez flexible et compatible avec HTTP c'est le protocole principal sur lequel Internet est basé. Comme il s’agit d’un style architectural et non de la norme, il fournit beaucoup de liberté pour mettre en œuvre diverses pratiques exemplaires de conception. Ai-je mentionné que cette langue est agnostique?
Dans cet article de blog, notre objectif sera d'expliquer REST le plus clairement possible afin que vous puissiez clairement comprendre quand et comment l'utiliser, ainsi que son contenu.
Nous allons passer en revue quelques notions de base et définitions, ainsi que Meilleures pratiques de l'API REST. Cela devrait vous donner toutes les connaissances dont vous avez besoin pour implémenter l'API REST dans la langue de votre choix.
Si vous n'êtes pas familier avec HTTP, je vous recommande de lire notre série HTTP, ou du moins la première partie de celui-ci, afin que vous puissiez digérer ces informations plus facilement.
Donc, dans ce post, nous allons parler de:
À propos de REST:
Meilleures pratiques de l'API REST:
Sommaire
Alors, qu'est-ce que le repos essentiellement?
REST (Representational State Transfer) est un style architectural fondé par Roy Fielding dans son doctorat. Mémoire intitulé «Styles architecturaux et conception d'architectures logicielles basées sur le réseau», UC Irvine. Il l'a développé en parallèle avec HTTP 1.1 (pas de pression).
Nous utilisons REST principalement comme un moyen communiquer entre des systèmes informatiques sur le World Wide Web.
REST est-il lié à HTTP?
Par définition, ce n’est pas le cas. Bien que vous puissiez utiliser un autre protocole d'application avec REST, HTTP est resté le champion incontesté des protocoles d'application en ce qui concerne la mise en œuvre de REST.
Support REST et HATEOAS
HATEOAS ou Hypermédia en tant que moteur de l'état de l'application est la fonctionnalité importante de chaque API REST évolutive et flexible.
La contrainte HATEOAS propose que le client et le serveur communiquent entièrement via l'hypermédia.
L'utilisation de l'hypermédia présente plusieurs avantages:
- Permet aux concepteurs d'API plutôt que d'inclure tout ce qu'ils peuvent dans chaque réponse, de fournir une chose correctement et des liens hypermédia aux points de terminaison associés et ainsi découpler la conception.
- Aide une API à évoluer et à mûrir plus gracieusement
- Donne à l'utilisateur le moyen d'explorer l'API plus en profondeur
Il est donc clair que le HATEOAS était conçu avec la durabilité à l'esprit.
Voici comment GitHub le fait:
OBTENIR https://api.github.com/users/codemazeblog |
Réponse:
1 2 3 4 5 6 sept 8 9 dix 11 12 13 14 15 16 17 18 19 20 21 22 23 24 |
{ "s'identifier": "CodeMazeBlog", "id": 29179238, "avatar_url": "https://avatars0.githubusercontent.com/u/29179238?v=4", "gravatar_id": "", "url": "https://api.github.com/users/CodeMazeBlog", "html_url": "https://github.com/CodeMazeBlog", "followers_url": "https://api.github.com/users/CodeMazeBlog/followers", "suivant_url": "https://api.github.com/users/CodeMazeBlog/following/other_user", "gists_url": "https://api.github.com/users/CodeMazeBlog/gists/gist_id", "starred_url": "https://api.github.com/users/CodeMazeBlog/starred/ownerBuch/repo", "subscriptions_url": "https://api.github.com/users/CodeMazeBlog/subscriptions", "organisations_url": "https://api.github.com/users/CodeMazeBlog/orgs", "repos_url": "https://api.github.com/users/CodeMazeBlog/repos", "events_url": "https://api.github.com/users/CodeMazeBlog/events/privacy", "receive_events_url": "https://api.github.com/users/CodeMazeBlog/received_events", "type": "Utilisateur", "site_admin": faux, "Nom": "Code Maze", "compagnie": "Code Maze", "Blog": "https://code-maze.com", "bio": "Une ressource pratique pour les programmeurs.", ...
|
Comme vous pouvez le constater, outre les informations cruciales demandées par le client, vous pouvez trouver dans la réponse de nombreux liens hypermédia connexes qui vous mènent à d’autres parties de l’API que vous pouvez explorer librement.
Que signifie API RESTful?
"RESTful", implique quelques caractéristiques:
- Architecture client-serveur: Le service complet est composé du «client» qui est le frontal et du «serveur» qui est la partie principale du système.
- Apatride: Le serveur ne doit sauvegarder aucun état entre différentes requêtes. L'état de la session est exclusivement laissé à la responsabilité du client. Selon la définition de REST: Toutes les interactions REST sont sans état. C'est-à-dire que chaque demande contient toutes les informations nécessaires à la compréhension d'un connecteur par un connecteur, indépendamment des demandes qui l'ont éventuellement précédée. (Thèse de Roy ch. 5.2.2)
- Cacheable: Le client doit pouvoir stocker les réponses dans un cache pour améliorer les performances.
Ainsi, l'API RESTful est un service qui respecte ces règles (espérons-le) et utilise des méthodes HTTP pour manipuler l'ensemble des ressources.
Mais pourquoi avons-nous besoin ou utilisons-ils des API RESTful?
Parce qu'ils nous offrent un moyen simple, flexible et évolutif de créer des applications distribuées qui communiquent sur Internet.
Peut-on avoir trop de repos?
Oui, vous l'avez deviné. Oui, nous pouvons
Il existe même une phrase pour les personnes qui suivent le REST de manière fanatique, comme l'a défini Mike Schinkel.
UNE RESTifarian est un partisan zélé du REST style architectural du logiciel tel que défini par Roy T. Fielding au chapitre 5 de sa thèse. thèse à UCIrvine. Vous pouvez trouver des RESTifarians à l'état sauvage sur la liste de diffusion REST-discussion. Mais soyez prudent, les RESTifarians peuvent être extrêmement méticuleux lorsqu’ils discutent des détails de REST, comme je l’ai appris récemment en participant à la liste. 🙂
Trop de tout peut être mauvais.
Nous avons besoin d'un peu pragmatisme faire de bonnes applications et services. Il est important de connaître et de comprendre une théorie, mais c'est son application qui permet de différencier les applications mauvaises, bonnes et excellentes. Alors, soyez intelligent, pensez à l'utilisateur final.
Voyons donc quelques points importants qui rendent l’API «brillante» et facilitent grandement la vie des utilisateurs.
API abstraites vs concrètes
Lors du développement de logiciels, nous utilisons souvent l’abstraction et le polymorphisme pour obtenir la plupart de nos applications. Nous voulons réutiliser le plus de code possible.
Alors devrions-nous écrire nos API de cette façon aussi?
Eh bien, ce n'est pas exactement le cas avec les API. Pour les API REST, le le béton vaut mieux que l'abstrait. Pouvez-vous deviner pourquoi?
Laissez-moi vous montrer quelques exemples:
Examinons deux versions de l’API. Est-il préférable d'avoir une API qui en a une / entités
ou une API qui a /les propriétaires
, / blogs
et / blogposts
séparément?
Lequel vous semble plus descriptif en tant que développeur? Quelle API préférez-vous utiliser?
Je choisirais toujours le second.
Mise en forme URI (noms, pas verbes). Bonne URL vs Mauvais URL
Voici une autre des meilleures pratiques des API REST. Comment devriez-vous formater vos points de terminaison?
Si vous utilisez l'approche de développement logiciel, vous obtiendrez quelque chose comme ceci:
/ getAllBlogPosts
/ updateBlogPost / 12
/ deleteBlogPost / 12
/ getAuthorById / 3
/ deleteAuthor / 3
/ updateAuthor / 3
Vous obtenez le point… Il y aura une tonne de points finaux, chacun faisant autre chose. Il existe un meilleur système pour régler ce gâchis.
Traitez la ressource comme un nom et la méthode HTTP comme un verbe. Si vous le faites comme ça, vous obtiendrez quelque chose comme ceci:
GET / blogposts
– récupère tous les articles du blog
GET / blogposts / 12
– récupère le blog avec l'identifiant 12
POST / blogposts
– ajoute un nouveau billet de blog et renvoie les détails
SUPPRIMER / blogs / 12
– supprime la publication de blog avec l'identifiant 12
GET / authors / 3 / blogposts
– récupère tous les articles de l'auteur avec l'identifiant 3
C'est un moyen plus propre et plus précis de créer une API. Il est immédiatement clair pour l'utilisateur final, et il y a une méthode à la folie.
Vous pouvez le rendre encore plus propre en utilisant singulier au lieu de pluriel pour les noms de ressources. Celui-là est à vous.
La gestion des erreurs
Un autre aspect important de la construction de l’API. Il existe quelques bons moyens de gérer les erreurs.
Voyons comment les meilleurs chiens le font:
Twitter:
- Demande:
OBTENIR https://api.twitter.com/1.1/account/settings.json
- Réponse: code d'état 400
"les erreurs":[[[["code":215,"message":"Mauvaises données d'authentification."]
Twitter vous donne le code d'état et le code d'erreur avec une brève description de la nature de l'erreur survenue. Ils vous laissent regarder les codes sur leur Codes de réponse page.
Facebook:
- Demande:
OBTENIR https://graph.facebook.com/me/photos
- Réponse: code d'état 400
"Erreur":
"message": "Un jeton d'accès actif doit être utilisé pour interroger des informations sur l'utilisateur actuel.",
"type": "OAuthException",
"code": 2500,
"fbtrace_id": "DzkTMkgIA7V"
Facebook vous donne un message d'erreur plus descriptif.
Twilio:
- Demande:
OBTENIR https://api.twilio.com/2010-04-01/Accounts/1234/IncomingPhoneNumbers/1234
- Réponse: code d'état 404
<?xml version='1.0' codage='UTF-8'?>
20404
La ressource demandée / 2010-04-01 / Accounts / 1234 / IncomingPhoneNumbers / 1234 est introuvable. https://www.twilio.com/docs/errors/20404 404
Twilio vous donne une réponse XML par défaut et le lien vers la documentation où vous pouvez trouver les détails de l'erreur.
Comme vous pouvez le constater, les méthodes de traitement des erreurs diffèrent d’une mise en oeuvre à l’autre.
La chose importante est ne pas laisser l'utilisateur de l'API REST «en suspens», ne sachant pas ce qui s’est passé ou errant sans but parmi les déchets de StackOverflow à la recherche de l’explication.
Codes de statut
Lors de la conception d'une API REST, nous communiquons avec l'utilisateur de l'API à l'aide des codes d'état HTTP. Il y a beaucoup de codes d'état, décrivant plusieurs réponses possibles.
Mais combien devrions-nous en utiliser? Devrions-nous avoir un code de statut strict pour chaque situation?
Comme pour beaucoup de choses dans la vie, le principe KISS s'applique ici aussi. Il existe plus de 70 codes d'état. Les connaissez-vous par coeur? L'utilisateur potentiel de l'API les connaîtra-t-il tous, ou cela aboutira-t-il à googler?
La plupart des développeurs connaissent les codes d'état les plus courants:
200 OK
400 mauvaise demande
500 Erreur de serveur interne
En commençant par ces trois, vous pouvez couvrir la plupart des fonctionnalités de votre API REST.
Parmi les autres codes couramment utilisés, citons:
201 créées
204 Pas de contenu
401 non autorisé
403 interdit
404 introuvable
Nous pouvons les utiliser pour aider l'utilisateur à comprendre rapidement le résultat. Nous devrions probablement inclure une sorte de message si vous estimez que le code d'état n'est pas assez descriptif, comme nous en avons discuté dans la section Traitement des erreurs. Encore une fois, il faut être pragmatique, aider l’utilisateur en utilisant un nombre limité de codes et des messages descriptifs.
Vous pouvez trouver la liste complète des codes d'état HTTP, ainsi que d'autres astuces HTTP utiles, résumées sur CodeMaze.
Sécurité
Il n’ya pas grand chose à dire sur la sécurité de l’API REST car REST ne traite pas de la sécurité. Il repose sur des mécanismes HTTP standard, tels que l'authentification de base ou l'authentification Digest.
Chaque demande doit être faite sur HTTPS.
Il existe de nombreuses astuces pour améliorer la sécurité de votre API REST, mais vous devez être prudent lors de leur implémentation, en raison de la nature sans état de REST. En se rappelant l’état de la dernière demande sort de la fenêtre, et le client est l'endroit où l'état doit être stocké et vérifié.
Horodatage et journalisation les demandes peuvent aider un peu aussi.
Il y a encore beaucoup à dire sur ce sujet, mais cela sort du cadre de cet article. Nous avons un bon post sur Sécurité HTTP ici sur CodeMaze si vous voulez en savoir plus à ce sujet.
Versioning de l'API REST
Vous avez déjà écrit votre API REST et cela a été un grand succès. Beaucoup de gens l’ont utilisée et en sont satisfaits. Mais vous avez cette nouvelle fonctionnalité juteuse qui casse d'autres parties du système. Le changement de rupture.
Ne craignez rien, il existe une solution pour cela!
Avant de commencer à créer votre API, nous pouvons la version en préfixant les points de terminaison avec la version de l'API:https://api.example.com/v1/authors/2/blogposts/13
De cette façon, nous pouvons toujours incrémenter le numéro de version de notre API (par exemple, v2, v3…) chaque fois que des changements importants se produisent dans notre API. Cela indique également aux utilisateurs que quelque chose de radical a changé et qu'ils doivent faire attention lorsqu'ils utilisent la nouvelle version.
Importance de la documentation
Celui-ci est la évidence. Vous pourriez être le meilleur concepteur d'API au monde, mais sans documentation, votre API est quasiment morte.
Une bonne documentation est essentielle pour chaque produit logiciel et service Web.
Nous pouvons aider l'utilisateur en étant cohérent et en utilisant une syntaxe claire et descriptive, bien sûr. Mais il n’ya pas de véritable remplaçant pour les pages de documentation du bon vieux.
Quelques exemples intéressants:
https://www.twilio.com/docs/api/rest/
https://developers.facebook.com/docs/
https://developers.google.com/maps/documentation/
et plein d'autres…
De nombreux outils peuvent vous aider à documenter votre API, mais n’oubliez pas d’ajouter le contact humain, seul un humain peut en comprendre un autre correctement. Pour le moment au moins (en regardant AI). 🙂
Conclusion
Nous avons examiné de nombreux concepts relatifs à la création d'une API REST et abordé certaines des meilleures pratiques en matière d'API REST Celles-ci peuvent sembler un peu étranges ou accablantes lorsqu'elles sont servies à la fois, mais essayez de créer votre propre API REST. Et essayez d'implémenter certaines des meilleures pratiques d'API REST que vous avez apprises ici.
Faites la plus petite API possible et voyez à quoi elle ressemble. Vous serez surpris de voir à quel point cela peut se passer simplement en suivant ces quelques pratiques.
Nous avons une série d’API Web ASP.NET Core dans lesquelles nous démontrons ces pratiques. Si vous êtes un développeur C #, consultez également notre article sur la façon de consommer les API RESTful de différentes manières.
Et avec cela dit, Je REPOSE mon cas… Kmhmh… parce que vous savez, sur le court… oh tant pis: /
Si vous avez aimé lire cet article et si vous souhaitez recevoir les notifications concernant le contenu .NET Core fraîchement publié, nous vous encourageons à:
abonnez-vous à notre blog.
Commentaires
Laisser un commentaire