Aller au contenu principal

Convention de nommage API REST

La représentation principale des données dans REST est appelée ressource. Une ressource correctement nommée rend une API simple à utiliser et intuitive. Cette même API, lorsqu’elle n’est pas implémentée correctement, peut sembler compliquée et difficile à utiliser et à comprendre. L’article suivant vous aidera à démarrer lors de la construction des URI de ressource pour votre nouvelle API.

<http://localhost:8888/restfulservices/v1/users/{id>}

http = Protocol localhost : host 8888 : port restfulservices : context de l'application v1 : version users : resource id : parametre

Utiliser des noms pour représenter des ressources / Pas de verbes​

Assurez-vous toujours que vos URI sont nommés avec des noms pour spécifier la ressource au lieu d’utiliser des verbes. Les URI ne doivent pas indiquer d’opérations CRUD (Create, Read, Update, Delete). De plus, évitez les combinaisons verbe-nom : trait d’union, snake_case, camelCase.

Mauvais exemples :

http://api.example.com/v1/store/CreateItems/{item-id}❌
http://api.example.com/v1/store/getEmployees/{emp-id}❌
http://api.example.com/v1/store/update-prices/{price-id}❌
http://api.example.com/v1/store/deleteOrders/{order-id}❌

Bons exemples :

http://api.example.com/v1/store/items/{item-id}✅
http://api.example.com/v1/store/employees/{emp-id}✅
http://api.example.com/v1/store/prices/{price-id}✅
http://api.example.com/v1/store/orders/{order-id}✅

Utiliser des noms pluriels pour les ressources​

Utilisez le pluriel lorsque cela est possible, sauf s’il s’agit de ressources singleton.

Mauvais exemples (ressources typiques et singleton) :

<http://api.example.com/v1/store/item/{item-id>}❌
<http://api.example.com/v1/store/employee/{emp-id}/address>❌

Bons exemples (ressources typiques et singleton) :

<http://api.example.com/v1/store/items/{item-id>}✅
<http://api.example.com/v1/store/employees/{emp-id}/address>✅

Utiliser des traits d’union (-) pour améliorer la lisibilité des URI​

N’utilisez pas de traits de soulignement. Séparer les mots par des traits d’union sera facile à interpréter pour vous et les autres. Il est plus convivial lorsqu’il s’agit d’URI segmentés à long chemin.

Mauvais exemples :

<http://api.example.com/v1/store/vendormanagement/{vendor-id>}❌
<http://api.example.com/v1/store/itemmanagement/{item-id}/producttype>❌
<http://api.example.com/v1/store/inventory_management>❌

Bons exemples :

<http://api.example.com/v1/store/vendor-management/{vendor-id>}✅
<http://api.example.com/v1/store/item-management/{item-id}/product-type>✅
<http://api.example.com/v1/store/inventory-management>✅

Utilisez des barres obliques (/) pour la hiérarchie, mais pas de barre oblique de fin (/)​

Les barres obliques sont utilisées pour montrer la hiérarchie entre les ressources individuelles et les collections.

Mauvais exemple :

<http://api.example.com/v1/store/items/>❌

Bons exemples :

<http://api.example.com/v1/store/items>✅

Évitez d’utiliser des extensions de fichier​

Ils sont inutiles et ajoutent de la longueur et de la complexité aux URI.

Mauvais exemples :

<http://api.example.com/v1/store/items.json>❌
<http://api.example.com/v1/store/products.xml>❌

Bons exemples :

<http://api.example.com/v1/store/items>✅
<http://api.example.com/v1/store/products>✅

Version de vos API​

Essayez toujours de versionner vos API. Vous pouvez fournir un chemin de mise à niveau sans apporter de modifications fondamentales aux API existantes en versionnant vos API. Vous pouvez également informer les utilisateurs que les versions mises à jour de l’API sont accessibles aux URI complets suivants.

<http://api.example.com/v1/store/employees/{emp-id>}

L’introduction dans toute mise à jour majeure peut être évitée avec le /v2 suivant.

<http://api.example.com/v1/store/items/{item-id>}
<http://api.example.com/v2/store/employees/{emp-id}/address>

Utiliser un composant de requête pour filtrer la collection d’URI​

Vous rencontrerez fréquemment des exigences qui vous obligeront à trier, filtrer ou limiter un groupe de ressources en fonction d’un attribut de ressource particulier. Au lieu de créer des API supplémentaires, activez le tri, le filtrage et la pagination dans l’API de collecte de ressources et donnez les paramètres d’entrée en tant que paramètres de requête pour répondre à cette exigence.

<http://api.example.com/v1/store/items?group=124>
<http://api.example.com/v1/store/employees?department=IT&region=USA>

Exemples​

GET — Lire l’employé avec l’ID d’employé 8345

example.com/employees/8345

POST— Créer un employé

example.com/employees

PATCH... Mettre à jour l’employé avec l’ID d’employé 8345

example.com/employees/8345

DELETE — Supprimer l’employé dont l’ID d’employé est 8345

example.com/employees/8345