Meilleures pratiques de codage pour la conception d’API de repos

JSON, points de terminaison, facteur, CRUD, Curl, HTTP, code d’état, demande, réponse, authentification,

Tous ces mots vous sont familiers si vous êtes dans le développement backend et que vous avez travaillé sur des API (Application Programming Interface). En tant que développeur, vous avez peut-être travaillé sur une sorte d’API (en particulier ceux qui sont des développeurs expérimentés). Peut-être une API de passerelle de paiement, une API Google Maps, des API d’envoi d’e-mails ou tout autre type d’API en fonction du type d’application et des exigences.

Il arrive souvent que les développeurs lisent la partie documentation de l’API, l’implémentent, mais ils ne se concentrent pas sur la construction d’une architecture propre, compréhensible et évolutive lorsqu’ils implémentent tout type d’API dans leur application. Ces éléments ont un impact considérable sur un système lorsque l’application se développe avec le temps.

Considérez un scénario dans lequel vous avez créé une application et vous devez maintenant exposer l’interface à l’utilisateur. Pensez-vous vraiment que vous serez tous les deux à la même table ? Pensez-vous qu’ils comprendront la même chose que vous essayez de décrire dans votre système ?

Lorsque vous créez une API Restful, il est important de la concevoir correctement pour éviter tout bogue ou problème dans votre application. Vous devez vous soucier des performances, de la sécurité et de la facilité d’utilisation pour les consommateurs d’API. Il est bon de suivre quelques bonnes conventions pour créer une API propre, compréhensible et facile à utiliser.

Il y a tellement d’aspects que vous devez prendre en compte lorsque vous créez une API Restful dans votre application. Dans ce blog, nous allons souligner ces aspects en détail. Discutons de la meilleure convention de codage pour créer l’API REST dans votre application.

1. Le nom du point de terminaison doit être accompagné de la méthode HTTP

En tant que développeur backend, vous connaissez peut-être les différentes méthodes de requête HTTP pour effectuer des actions CRUD dans votre application, en particulier celles qui sont courantes telles que GET, POST, PUT, DELETE et PATCH. Au cas où vous n’êtes pas familier avec ces méthodes alors lisez le blog Méthodes de requête HTTP.

Lorsque vous implémentez une API, assurez-vous que le nom des points de terminaison liés aux ressources correspond à la méthode HTTP liée aux actions que vous utilisez dans votre application. Regardez l’exemple ci-dessous pour référence…

– GET /get_customers – POST /insert_customers – PUT /modify_customers – DELETE /delete_customers + GET /customers + POST /customers + PUT /customers + DELETE /customers

2. Renvoyez les codes d’erreur standard en fonction du résultat de notre API

Lors de la mise en œuvre d’une API, les points de terminaison renvoient le résultat indiquant si l’action est réussie ou non. Le résultat est toujours associé à un code d’état. Par exemple : si vous obtenez le statut 200 (ok), cela signifie que le résultat est réussi et si vous obtenez le code de statut 400 (mauvaise demande), le résultat échoue (vous pouvez vérifier la réponse à l’aide de certains outils comme Postman pour accéder à connaître le code d’état des actions que vous effectuez dans votre application).

Gérez les erreurs correctement et renvoyez le code de réponse HTTP pour indiquer le type d’erreur généré. Ceci est utile pour les responsables de l’API pour comprendre les problèmes et les résoudre.

Assurez-vous de connaître le code de statut existant pour identifier le cas dont vous avez besoin pour appliquer chacun d’eux. Parfois, il arrive que le message de retour ne corresponde pas au code d’état et cela crée une confusion pour les développeurs ainsi que pour les consommateurs qui utilisent cette API REST. C’est vraiment dommageable pour l’application. Il est donc bon de prendre soin du code d’état des actions que vous effectuez dans votre application. Ci-dessous, un des exemples…

// Mauvais, code d’état 200 (Success) // associé à un objet d’erreur { « status »: 200, « error »: {…} }// Good { « status »: 200, « data »: […]
}

Certains codes d’erreur courants sont donnés ci-dessous…

• 00 Bad Request – L’entrée côté client échoue à la validation.
• 401 Non autorisé – L’utilisateur n’est pas autorisé à accéder à une ressource. Il revient généralement lorsque l’utilisateur n’est pas authentifié.
• 403 Interdit – L’utilisateur est authentifié, mais il n’est pas autorisé à accéder à une ressource.
• 404 Not Found – La ressource est introuvable.
• 500 Erreur de serveur interne – Erreur de serveur générique. Il ne devrait probablement pas être lancé explicitement.
• 502 Bad Gateway – Ceci indique une réponse non valide d’un serveur en amont.
• 503 Service non disponible – Quelque chose d’inattendu s’est produit côté serveur (cela peut être quelque chose comme une surcharge du serveur, certaines parties du système ont échoué, etc.).

3. Prise en charge du filtre, du tri et de la pagination

Comment réagirait votre serveur si vous implémentiez une API dans votre application et que les points de terminaison renvoient les résultats en millions….???

Votre serveur sera en panne et il va vraiment pleurer devant vous…(blague à part…)

Il arrive souvent que nous n’ayons besoin de consommer que des ressources spécifiques ou moins de notre serveur. La raison peut être n’importe quoi. Il peut s’agir des performances du système, du système de recherche ou de la quantité massive d’informations qu’il n’est pas nécessaire de renvoyer en une seule fois. Vous pouvez utiliser un filtre pour renvoyer un article spécifique en fonction de la condition. Si vous souhaitez renvoyer quelques résultats à la fois, utilisez la pagination dans votre API.

Ces concepts vous aideront à n’afficher qu’un type spécifique d’informations et augmenteront les performances de votre système en consommant moins de ressources. Des exemples sont donnés ci-dessous…

• Filtre: filtrez le client avec les propriétés suivantes… le nom de famille est Smith et l’âge est 30.
  GET /customers?last_name=Smith&age=30
• Pagination: Renvoie 20 lignes à partir de 0
  OBTENIR /clients?limit=20&offset=0
• Sorte: Renvoyer les lignes triées par email dans l’ascendant.
  GET /customers?sort_by=asc(email)

4. Le nom des points de terminaison doit être au pluriel

Si vous avez implémenté tout type d’API dans votre application, vous vous êtes peut-être posé la question de savoir si le nom du point de terminaison doit être au singulier ou au pluriel. N’oubliez pas que vous devez maintenir la cohérence tout au long de votre application. Il est donc bon de construire les points de terminaison au pluriel pour être cohérents dans votre base de données.

Il n’est pas nécessaire que vous obteniez toujours un seul article. Vous pouvez avoir de nombreux éléments dans un tableau, mais même si vous envisagez le scénario d’obtenir le résultat un seul et que vous le placez au singulier partout, vous ne pourrez pas maintenir la cohérence dans le nom de vos itinéraires.

– GET /article – GET /article/:id + GET /articles + GET /articles/:id

5. Imbrication de ressources pour les objets hiérarchiques

Lors de la mise en œuvre d’une API, vous devez vous occuper du chemin des points de terminaison. Le chemin du point de terminaison traite des ressources imbriquées. Pour créer ce chemin, traitez la ressource imbriquée comme le nom du chemin et ajoutez-la après la ressource parent. Assurez-vous que la ressource imbriquée correspond à la table que vous avez stockée dans votre base de données, sinon cela créera une confusion pour vous.

Si vous ne comprenez pas le point ci-dessus, comprenez-le de manière à avoir une liste d’étudiants dans votre base de données. Chacun d’eux a choisi les sujets qui l’intéressent. Traitez la table « sujet » comme un enfant d’une table « étudiant » dans votre base de données.

Maintenant, si vous souhaitez créer le point de terminaison pour les matières associées à l’étudiant, ajoutez le chemin /sujets à la fin du chemin /étudiant. Si vous utilisez la méthode GET, un exemple de chemin de point de terminaison ressemblera à celui donné ci-dessous…

‘/students/:studentId/subjects’

Nous obtenons des sujets sur les étudiants identifiés par studentId, puis la réponse sera renvoyée. Ici, les étudiants sont les ressources des parents et le sujet est les ressources de l’enfant de l’étudiant. Donc, comme discuté, nous ajoutons des sujets après le ‘/students/:studentId’. Chaque élève a sa propre matière. Le même type de structure d’imbrication sera appliqué à d’autres méthodes telles que les points de terminaison POST, PUT et DELETE.

6. Suivez les bonnes pratiques de sécurité

Lorsque vous implémentez une API, assurez-vous que la communication entre le client et le serveur est privée car vous envoyez et recevez souvent des informations privées. Pour des raisons de sécurité, vous pouvez utiliser SSL/TLS.

L’utilisation du certificat SSL n’est pas trop difficile. Vous pouvez facilement le charger sur le serveur et le coût d’un certificat SSL est également gratuit et très faible. N’ouvrez pas votre API REST. Il doit communiquer via des canaux sécurisés.

Lorsqu’un utilisateur accède aux informations, il ne devrait pas être en mesure d’accéder à plus de données qu’il a demandées. En tant qu’utilisateur, vous n’êtes pas autorisé à accéder aux informations d’un autre utilisateur ou aux données des administrateurs.

Pour mettre en œuvre le principe du moindre privilège, ajoutez des contrôles de rôle pour un seul rôle ou des rôles plus granulaires pour chaque utilisateur. Si vous souhaitez regrouper les utilisateurs dans quelques rôles, ils doivent être autorisés à couvrir tout ce dont ils ont besoin et pas plus.

Pour chaque fonctionnalité à laquelle les utilisateurs ont accès, si vous disposez d’une autorisation plus précise, assurez-vous que les administrateurs peuvent facilement ajouter et supprimer ces fonctionnalités pour chaque utilisateur en conséquence. Ajoutez des rôles prédéfinis pouvant être appliqués aux utilisateurs du groupe. Vous n’aurez pas à le faire manuellement pour chaque utilisateur.

7. Cachez les données pour augmenter les performances

Vous avez peut-être utilisé la mise en cache lors de la mise en œuvre de certaines fonctionnalités dans votre application. La mise en cache est vraiment un outil puissant pour accélérer les performances de votre application. En utilisant la mise en cache, vous obtiendrez des résultats plus rapides et vous n’aurez pas à extraire les données de la base de données plusieurs fois pour la même requête.

Utilisez la mise en cache lors de la mise en œuvre de votre API. Cela accélérera les performances de votre application et réduira la consommation des ressources. Il est préférable de mettre en cache les données au lieu d’exécuter la même requête et de demander à la base de données de donner le même résultat (votre base de données se mettra à pleurer devant vous….lolzzz).

L’une des précautions à prendre est de ne pas obtenir de données obsolètes. En raison des anciennes données, un problème peut survenir et votre système peut générer de nombreux bogues dans un environnement de production. Ne conservez pas les informations pendant une longue période dans le cache. Il est bon de conserver les données pendant une courte période dans le cache.

En fonction de la…