13 bonnes pratiques pour la création d'API RESTful

Facebook, GitHub, Google et de nombreux autres géants ont besoin d'un moyen de diffuser et de consommer des données. Une API RESTful reste l’un des meilleurs choix dans le paysage de développement d’aujourd’hui pour servir et consommer des données.

Mais avez-vous déjà envisagé de vous familiariser avec les normes du secteur? Quelles sont les meilleures pratiques pour concevoir une API RESTful? En théorie, n'importe qui peut rapidement lancer une API de données en moins de cinq minutes, que ce soit Node.js, Golang ou Python.

Nous allons explorer 13 bonnes pratiques à prendre en compte lors de la création d'une API RESTful. Mais d'abord, clarifions rapidement une API RESTful.

Qu'est-ce qu'une API RESTful?

Une API RESTful doit répondre aux contraintes suivantes pour être appelée API RESTful.

1. Client-serveur : Une API RESTful suit le modèle client-serveur où le serveur sert des données et les clients se connectent au serveur pour consommer des données. L'interaction entre le client et le serveur se produit via des requêtes HTTP (S) qui transfèrent les données demandées.

2. Stateless : Plus important encore, une API RESTful doit être sans état. Chaque demande est traitée comme une demande autonome. Le serveur ne doit garder trace d'aucun état interne qui pourrait influencer le résultat des demandes futures.

3. Interface uniforme : Enfin, l'uniformité définit la façon dont le client et le serveur interagissent. Les API RESTful définissent les meilleures pratiques pour nommer les ressources, mais définissent des opérations HTTP fixes qui vous permettent de modifier / d'interagir avec les ressources. Les opérations HTTP suivantes sont accessibles dans les API RESTful:

   • Demande GET: récupérer une ressource
   • Demande POST: créer une ressource ou envoyer des informations à l'API
   • Demande PUT: créer ou remplacer une ressource
   • PATCH request: mettre à jour une ressource existante
   • DELETE request: supprimer une ressource

Grâce à cette compréhension plus approfondie des caractéristiques d'une API RESTful, il est temps d'en savoir plus sur les meilleures pratiques de l'API RESTful.

Best Practices For Designing Your First API RESTful

Cet article vous présente une liste exploitable de 13 meilleures pratiques. Explorons!

1. Utilisez correctement les méthodes HTTP

Nous avons déjà discuté des méthodes HTTP que vous pouvez utiliser pour modifier les ressources: GET, POST, PUT, PATCH et DELETE.

Pourtant, de nombreux développeurs ont tendance à abuser de GET et POST, ou PUT et PATCH. Souvent, nous voyons les développeurs utiliser une requête POST pour récupérer des données. De plus, nous voyons que les développeurs utilisent une requête PUT qui remplace la ressource alors qu'ils ne voulaient mettre à jour qu'un seul champ pour cette ressource.

Assurez-vous d'utiliser la bonne méthode HTTP car cela ajoutera beaucoup de confusion pour les développeurs utilisant votre RESTful API. Il vaut mieux s'en tenir aux directives prévues.

2. Conventions de dénomination

Comprendre les conventions de dénomination de l'API RESTful vous aidera beaucoup à concevoir votre API de manière organisée. Concevez une API RESTful en fonction des ressources que vous servez.

Par exemple, votre API gère les auteurs et les livres (oui, un exemple classique). Maintenant, nous voulons ajouter un nouvel auteur ou accéder à un auteur avec l'ID 3 . Vous pouvez concevoir les routes suivantes pour atteindre cet objectif:

• api.com/addNewAuthor
• api.com/getAuthorByID/3

Imaginez une API qui héberge de nombreuses ressources ayant chacune de nombreuses propriétés. La liste des points de terminaison possibles deviendra infinie et peu conviviale. Nous avons donc besoin d'une manière plus organisée et standardisée de concevoir les points de terminaison d'API.

Les meilleures pratiques de l'API RESTful décrivent qu'un point de terminaison doit commencer par le nom de la ressource, tandis que l'opération HTTP décrit l'action. Maintenant, nous obtenons:

• POST api.com/authors[19659010[/GETapicom/authors/3

) Que faire si nous voulons accéder à tous les livres que l'auteur avec l'ID 3 a déjà écrits? Dans ce cas également, les API RESTful ont une solution:

• GET api.com/authors/3/books[19659026unityEnfinquefairesivousvoulezsupprimerunlivreavecl'ID 5 pour un auteur avec ID 3 . Encore une fois, suivons la même approche structurée pour former le point de terminaison suivant:
  • DELETE api.com/authors/3/books/5

  En bref, utilisez les opérations HTTP et la méthode structurée de mappage de ressources pour former un chemin d'accès au point de terminaison lisible et compréhensible. Le gros avantage de cette approche est que chaque développeur comprend comment les API RESTful sont conçues et qu'il peut immédiatement utiliser l'API sans avoir à lire votre documentation sur chaque endpoint.

  3. Utiliser des ressources plurielles

  Les ressources doivent toujours utiliser leur forme plurielle. Pourquoi? Imaginez que vous vouliez récupérer tous les auteurs. Par conséquent, vous appelleriez le point de terminaison suivant: GET api.com/authors[19459019[19659003)Lorsquevouslisezlarequêtevousnepouvezpasdiresilaréponsedel'APIcontiendraunseuloutouslesauteursPourcetteraisonlespointsdeterminaisond'APIdoiventutiliserplusieursressources

  4. Utilisation correcte des codes d'état

  Les codes d'état ne sont pas là uniquement pour le plaisir. Ils ont un objectif clair. Un code d'état informe le client de la réussite de sa demande.

  Les catégories de code d'état les plus courantes sont:

  • 200 (OK): la demande a été traitée et terminée avec succès.
  • 201 (Créé): indique la création réussie d'une ressource.
  • 400 (demande incorrecte): représente une erreur côté client. Autrement dit, la requête a été mal formulée ou les paramètres de la requête sont manquants.
  • 401 (Non autorisé): Vous avez essayé d'accéder à une ressource pour laquelle vous n'avez pas l'autorisation.
  • 404 (Not Found): La ressource demandée ne l'est pas existe.
  • 500 (Erreur de serveur interne): Chaque fois que le serveur lève une exception lors de l'exécution de la requête.

  Une liste complète des codes d'état est disponible sur Mozilla Developers . N'oubliez pas de consulter le code d'état «Je suis une théière» (418).

  5. Respectez les conventions de casse

  Le plus souvent, une API RESTful sert des données JSON. Par conséquent, la convention d'enveloppe camelCase doit être appliquée. Cependant, différents langages de programmation utilisent différentes conventions de dénomination .

  6. Comment gérer la recherche, la pagination, le filtrage et le tri

  Les actions telles que la recherche, la pagination, le filtrage et le tri ne représentent pas des points de terminaison distincts. Ces actions peuvent être accomplies en utilisant les paramètres de requête fournis avec la requête API.

  Par exemple, récupérons tous les auteurs triés par nom dans l'ordre croissant. Votre requête API doit ressembler à ceci: api.com/authors?sort=name_asc .

  En outre, je souhaite récupérer un auteur avec le nom «Michiel». La requête ressemble à ceci api.com/authors?search=Michiel .

  Heureusement, de nombreux projets d'API sont dotés de fonctionnalités intégrées de recherche, de pagination, de filtrage et de tri. Cela vous fera gagner beaucoup de temps.

  7. Gestion des versions d'API

  Je ne vois pas cela très souvent, mais il est recommandé de procéder à la version de votre API. C'est un moyen efficace de communiquer les changements de rupture à vos utilisateurs.

  Souvent, le numéro de version de l'API est incorporé dans l'URL de l'API, comme ceci: api.com/v1/authors/3/books .

  Les en-têtes HTTP permettent à un client d'envoyer des informations supplémentaires avec sa requête. Par exemple, l'en-tête Authorization est couramment utilisé pour envoyer des données d'authentification pour accéder à l'API.

  Une liste complète de tous les en-têtes HTTP possibles peut être trouvée ici .

  9 . Limitation de débit

  La limitation de débit est une approche intéressante pour contrôler le nombre de requêtes par client. Voici les en-têtes de limitation de débit que votre serveur peut renvoyer:

  • X-Rate-Limit-Limit: indique le nombre de requêtes qu'un client peut envoyer dans un intervalle de temps spécifié.
  • X-Rate-Limit-Remaining: Indique le nombre de demandes que le client peut encore envoyer dans l'intervalle de temps actuel.
  • X-Rate-Limit-Reset: Indique au client quand la limite de débit sera réinitialisée.

  10. Gestion des erreurs significative

  En cas de problème, il est important que vous fournissiez un message d'erreur significatif au développeur. Par exemple, l'API Twilio renvoie le format d'erreur suivant:

   {
      "statut": 400,
      "message": "Les livres de ressources n'existent pas",
      "code": 24801,
      "more_info": "api.com/docs/errors/24801"
  }
  

  Dans cet exemple, le serveur renvoie le code d'état et un message lisible par l'homme. En outre, un code d'erreur interne est également renvoyé pour que le développeur recherche l'erreur spécifique. Cela permet au développeur de rechercher rapidement plus d'informations sur l'erreur.

  11. Choisissez le bon framework d'API

  De nombreux frameworks existent pour différents langages de programmation. Il est important de choisir un framework qui prend en charge les meilleures pratiques de l'API RESTful.

  Pour Node.js, les développeurs back-end adorent utiliser Express.js tandis que pour Python, Falcon est une excellente option.

  12. Documentez votre API

  Enfin, rédigez de la documentation! Je ne plaisante pas; c'est toujours l'un des moyens les plus simples de transférer des connaissances sur votre API nouvellement développée.

  Bien que votre API suive toutes les meilleures pratiques décrites pour les API RESTful, cela vaut toujours la peine de documenter divers éléments tels que les ressources que votre API gère ou le taux des limites s'appliquent à votre serveur.

  Pensez à vos collègues développeurs. La documentation réduit considérablement le temps nécessaire pour connaître votre API.

  13. Restez simple!

  Ne compliquez pas trop votre API et simplifiez les ressources. Une définition correcte des différentes ressources gérées par votre API vous aidera à éviter les problèmes liés aux ressources à l'avenir. Définissez vos ressources, mais définissez également avec précision ses propriétés et les relations entre les ressources. De cette façon, il n'y a pas de place pour la contestation sur la façon de connecter les différentes ressources.

  Si vous avez aimé cet article expliquant les meilleures pratiques d'API, vous pourriez également apprécier de découvrir la création d'une API RESTful à partir de zéro .