7 bonnes pratiques pour nommer vos points de terminaison d’API

Un point de terminaison API est un point de connexion entre deux logiciels. Les API ont des points de terminaison pour chaque ressource. Les points de terminaison spécifient l’emplacement exact d’une ressource sur le serveur.

Lorsqu’une application cliente demande des informations au serveur, elle passe par l’API. Qui accède ensuite à la demande et traite une réponse du serveur. L’API transfère ensuite les informations demandées du point de terminaison à l’application.

Votre API est efficace si elle peut communiquer efficacement via ses endpoints. Il facilite l’accès des utilisateurs aux ressources, améliorant ainsi l’expérience utilisateur.

Comment fonctionne un point de terminaison d’API ?

Les systèmes intégrés communiquent via des API. Un système envoie une requête à l’API, en utilisant un format tel que SOAP ou REST. Le serveur reçoit les requêtes et renvoie la réponse à l’API. L’emplacement de cette ressource demandée est le point de terminaison.

Avant qu’un point de terminaison traite une demande, le client doit fournir une URL, des en-têtes et un corps. Les en-têtes contiennent des métadonnées sur une demande et les données de détails du corps envoyées au serveur. Un serveur peut également se connecter à une base de données à laquelle les méthodes API peuvent accéder.

Les points de terminaison d’API fonctionnent généralement avec des méthodes HTTP telles que GET, DELETE, PATCH ou POST. Les méthodes déterminent comment utiliser un point de terminaison. Lorsqu’un client envoie une requête, il doit la formuler pour inclure la méthode de requête ainsi que l’URL, par exemple :

GET https://example.com/books/authors

La dénomination est difficile, qu’il s’agisse de points de terminaison d’API, de périphériques matériels en réseau ou de fonctions et de variables. Vous devriez en savoir plus sur certaines bonnes pratiques que vous pouvez utiliser pour vous assurer que vos points de terminaison d’API sont un atout.

1. Utilisez une barre oblique

Utilisez toujours des barres obliques pour séparer les ressources URI. Les barres obliques aident également à montrer la hiérarchie des ressources. Ce qui suit est un exemple:

2. Utilisez des noms, pas des verbes

Vous ne devez utiliser que des noms pour nommer une ressource. Les noms décrivent à quoi sert une ressource par opposition à un verbe qui décrit ce que fait une ressource. Voici un exemple d’une bonne et d’une mauvaise façon de nommer les points de terminaison de l’API.

Bonne dénomination :

Mauvaise dénomination :

http://example.com/api/books

3. Utilisez des noms au pluriel, pas au singulier

Vous devez toujours nommer vos points de terminaison d’API au pluriel. Cela indique à un utilisateur qu’il y a plus d’une ressource sur le serveur. L’utilisation d’un nom au singulier peut confondre l’utilisateur en lui faisant croire qu’il n’y a qu’une seule ressource.

Bonne dénomination :

Mauvaise dénomination :

http://example.com/api/books/3

4. Utilisez des lettres minuscules

Vous devez saisir toutes les URL en minuscules. Cela inclut les URL de point de terminaison d’API. Voici un exemple:

Bonne dénomination :

http://example.com/api/Books/3

Mauvaise dénomination :

http://example.com/api/books/3

5. Utilisez des tirets pour séparer les mots

Utilisez des traits d’union pour séparer les mots combinés. Les traits d’union donnent des phrases plus lisibles que la casse camel ou les traits de soulignement. Ils sont également meilleurs à des fins de référencement.

Bonne dénomination :

Mauvaise dénomination :

6. N’ajoutez pas d’extensions de fichier

Vous n’avez pas besoin d’ajouter une extension de fichier à vos points de terminaison d’API. Bien qu’elle n’affecte pas la sortie, une extension rend plus difficile la lecture de la ressource. Cela rend également la ressource moins flexible, la cassant si l’extension change à l’avenir.

Bonne dénomination :

Mauvaise dénomination :

7. Inclure la gestion des versions

Vous devez toujours nommer vos points de terminaison d’API en fonction de la version. Ceci est important si vous apportez des modifications majeures à l’API. Cela permet de différencier deux ou plusieurs versions d’API d’où provient la ressource. Vous pouvez indiquer la version au début du point de terminaison.

Par example:

Pourquoi considérer les meilleures pratiques d’API ?

Les API sont devenues l’épine dorsale de la programmation moderne. Ils améliorent la collaboration, encouragent l’innovation et améliorent la sécurité des applications.

Que vous utilisiez de nouveaux outils ou que vous gériez des outils existants, les API simplifient le processus. Il est donc essentiel d’avoir des endpoints qui améliorent l’expérience utilisateur. La dénomination et la structure de vos points de terminaison d’API déterminent les performances de votre API.

Assurez-vous d’utiliser les meilleures pratiques pour créer des points de terminaison d’API efficaces.