Configurez-vous correctement vos points de terminaison REST API ?
Configurez-vous correctement vos points de terminaison API ? C'est souvent lors de la configuration des points de terminaison de nos API que nous nous trouvons dans des situations où nous ne sommes pas sûrs s'il faut utiliser la forme plurielle ou singulière. Devrions-nous utiliser des traits de soulignement ou des tirets ? Comment mentionner les ID ? Pour une API qui crée une ressource, devrions-nous utiliser /resource/create ? Et bien d'autres encore. Plongeons donc dans les conventions de nommage pour les API REST. Nous couvrirons :
- Points de terminaison
- Méthodes
- Versioning
Points de terminaison
Commençons par examiner certaines conventions de nommage pour les API REST.
Ressources en tant que noms
Les API REST doivent vous permettre de manipuler une ressource en utilisant l'une des principales méthodes HTTP. Les URI REST ne doivent indiquer aucun type d'opération CRUD. Elles doivent faire référence à une ressource plutôt qu'à une action/verbe. Whenever possible, utilisez uniquement les formes plurielles des noms, sauf s'il s'agit de ressources singleton.
Bons exemples :
- https://api.website.com/v1/store/products
- https://api.website.com/v1/store/customers
- https://api.website.com/v1/store/discounts
Mauvais exemples :
- https://api.website.com/v1/store/createproducts
- https://api.website.com/v1/store/updatecustomers
- https://api.website.com/v1/store/getdiscounts
Hiérarchie
La hiérarchie entre les ressources et les collections est définie par l'utilisation de barres obliques.
« Comme dans tous les domaines du métier de développeur de logiciels, le nommage est essentiel au succès »
Bon exemple :
- https://api.website.com/v1/item/store
Mauvais exemple :
- https://api.website.com/v1/store/items
Tirets
Il est largement admis que lire des tirets ( first-name ) est plus clair et convivial que de lire des traits de soulignement ( first_name ). Par conséquent, chaque fois qu'un point de terminaison API REST contient plusieurs mots, il est toujours préférable d'utiliser des tirets à la place des traits de soulignement. De plus, il y a un angle ici du point de vue du référencement également. Il est recommandé d'utiliser des tirets car cela aide les robots à identifier plus facilement les concepts dans l'URL. Et un trait de soulignement entre deux mots est considéré comme un mot entier, tandis que l'utilisation de tirets est considérée comme deux mots séparés.
Bon exemple :
- https://api.website.com/v1/store/inventory-management/active-orders
Mauvais exemple
- https://api.website.com/v1/store/inventory_management/active_orders
Méthodes
Nous savons maintenant ne pas utiliser de verbes dans nos points de terminaison API REST, mais cela soulève la question de savoir comment spécifier le verbe. Pour cela, nous avons les méthodes HTTP à notre secours. Les méthodes HTTP sont les verbes qui indiquent le type d'opération que l'API pourrait exécuter.
Méthodes HTTP :
- GET correspond à l'opération « Lecture » d'une ressource ou d'une collection.
- POST correspond à l'opération « Créer » d'une ressource ou d'une collection.
- PUT correspond à l'opération « Mettre à jour » d'une ressource ou d'une collection.
- DELETE correspond à l'opération « SUPPRIMER » d'une ressource ou d'une collection.
Il y a un total de 39 méthodes HTTP, mais GET, POST, PUT et DELETE sont les méthodes les plus couramment utilisées et les plus basiques. Nous couvrirons toutes les méthodes HTTP et leurs cas d'utilisation dans un blog séparé.
Versioning
Il est toujours préférable de versioner vos API. Les mêmes URL peuvent être consommées sans avoir à apporter de modifications majeures aux points de terminaison API REST. Les points de terminaison API ne doivent jamais être invalidés car cela pourrait avoir des conséquences imprévues pour les applications qui les consomment.
Exemples :
- https://api.website.com/v1/store/items
- https://api.webiste.com/v2/store/employees
Points clés
- Utilisez des noms pour représenter les ressources.
- Évitez d'utiliser des verbes dans les points de terminaison API REST.
- N'utilisez pas de traits de soulignement (`_`) dans un point de terminaison. Utilisez plutôt des tirets (`-`).
- Utilisez les requêtes pour filtrer, trier ou limiter une collection API.
- N'ajoutez jamais d'extensions de fichier aux URL. Si vous souhaitez spécifier le type de contenu, utilisez l'en-tête `Content-Type`.
- Préférez toujours utiliser des minuscules dans les points de terminaison API REST.
- Ne mettez pas de barres obliques à la fin (`/`) dans les points de terminaison des API Rest. Elles n'ajoutent aucune valeur sémantique et peuvent être confuses.
- Choisissez des noms simples. Si c'est bien fait, les points de terminaison API deviendront très faciles pour n'importe quel développeur à retenir ou à deviner.
