Convention de nommage
doitAppliquer comme convention de nommage :- lowerCamelCase ou snake_case pour les contenus (attributs JSON)
- kebab-case pour les contenants (URLs)
Les contraintes techniques des frameworks ou stacks mis en oeuvre sont souvent utilisées à tort comme argument pour décider de choisir la convention snake_case plutôt que kebab-case.
Bien que ce débat ne soit pas véritablement tranché, le fait est que la majorité des solutions de blogs (sensibles par définition aux optimisations SEO et aux standards du web) ont opté pour kebab-case (appelé aussi "hyphen-separated-case").
doitLes noms d'attributs doivent toujours respecter un encodage ASCII, avec comme premier caractère une lettre, $, ou \_ (pas de chiffre), chaque caractère suivant peut être une lettre, $, \_ ou un chiffre.URLs et actions
Les URLs et actions d'une API représentent la carte qui permet de naviguer dans le SI.
Une API est organisée en ressources logiques localisées par leur URI et manipulées par un verbe, verbe représenté par une méthode HTTP (GET, POST, PUT, PATCH, DELETE).
Ces principes forts du style d'architecture REST ont été introduits par Roy Fielding dans sa thèse sur les architectures logicielles basées sur les réseaux, plus précisément au chapitre 5.
doitChoisir la bonne méthode pour la bonne action :| Méthode | Action | Situation | Remarques |
|---|---|---|---|
| GET | lister, obtenir | obtenir la représentation d'une ressource | le SI n'est pas modifié (idempotence) |
| POST | ajouter | ajouter un élément dans une collection de ressources | le SI est modifié et souvent un identifiant est généré pour la nouvelle ressource créée (et communiqué via l'en-tête Location) |
| PUT | modifier complètement | remplacer une ressource | le payload soumis est censé représenter complètement la ressource, c'est-à-dire que la ressource peut être écrasée par les données envoyées |
| PATCH | modifier partiellement | mettre à jour une ressource partiellement | les données composantes de la ressource existante et non présentes dans le payload restent inchangées |
| DELETE | supprimer, purger | supprimer, détruire une ressource, ou vider une collection de ressources | classiquement la réponse ne contient pas de corps et le statut est 204 |
| HEAD | vérifier | vérifier l'obtention d'une ressource, obtenir des méta données | aucun corps / aucune représentation n'est retournée dans la réponse; rarement utilisée, cette méthode peut servir à vérifier la localisation d'une ressource |
| OPTIONS | se renseigner | obtenir des informations sur les modalités de la communication | permet au client d'en savoir plus sur les prérequis d'une ressource; très rarement implémenté |
Il est à noter que la méthode POST est parfois utilisée comme méthode de remplacement de PUT, PATCH ou DELETE, dans des situations d'exceptions comme un client ne supportant pas toutes les méthodes (navigateur obsolète).
Dans une telle situation, on utilise la méthode POST en précisant la "vraie" méthode dans un en-tête "X-HTTP-Method-Override" ou un paramètre de requête "_method"; la plupart des frameworks pour applications web sont censés supporter ce fallback.
Le fait qu'un service web propose cette souplesse de fonctionnement ne l'affranchit absolument pas de respecter le standard, les deux modes n'étant pas exclusifs.
Nommage d'une ressource (URI)
doitUne ressource doit représenter un nom commun ("noun"), de préférence en anglais car la localisation d'une ressource ne doit pas préjuger de la langue de préférence du consommateur (l'anglais étant le choix le plus générique possible).La sémantique est la chose la plus importante à avoir en tête pour obtenir un bon nommage.
Exemples :
| Ressource | Nom |
|---|---|
| Une pizza | pizza |
| Un client | customer |
| Le client 3 | customers/3 |
| L'adresse du client 4 | customers/4/address |
| L'email 3 de l'utilisateur 2 | users/2/emails/3 |
Dans certaines situations exceptionnelles, où il paraît délicat de respecter ce principe, on utilise une forme RPC, néanmoins cela reste une enfreinte aux bonnes pratiques.
Concrètement lorsque l'on est résigné à choisir un style RPC, on utilise un verbe plutôt qu'un nom commun; le verbe désignant explicitement une action.
Exemples RPC :
| Ressource | Nom |
|---|---|
| S'enregistrer | signup |
| Se connecter | signin |
| Supprimer une page des favoris | pages/4/unstar |
Sémantique
Pour nommer efficacement une ressource, utiliser des moyens mnémotechniques simples en prononçant mentalement des phrases adaptées au besoin.
Exemples :
| Besoin | Traduction sémantique | Nommage résultant |
|---|---|---|
| Obtenir l'adresse de l'utilisateur 7 | Obtenir l'adresse de l'élément 7 de la collection des utilisateurs | GET /customers/7/address |
| Obtenir la facture de mon compte | ... | GET /account/invoice |
| Créer un client | Poster un élément dans la collection des clients | POST /customers |
Conseil : consacrez tout le temps nécessaire à la définition d'une bonne sémantique, vous ne le regrettez pas.
Pluriel
Dans la plupart des cas, les ressources à concevoir désignent une collection permettant d'ajouter ou de supprimer des éléments.
La collection désigne alors naturellement un pluriel, tandis que l'élément désigne un singulier.
Néanmoins, un élément peut être vu comme un sous-ensemble d'une collection, sa localisation se résumant alors à un sous-chemin par rapport à la collection (un singulier n'est qu'un item d'un pluriel).
devraitAfin de rendre les chemins de ressources consistants et intuitifs, on privilégie l'utilisation du pluriel plutôt que le singulier.Exemple appliqué à CRUD :
| Besoin | Ressource |
|---|---|
| Obtenir les pizzas | GET /pizzas |
| Créer une pizza | POST /pizzas |
| Obtenir la pizza carbonara | GET /pizzas/carbonara |
| Modifier la pizza carbonara | PUT /pizzas/carbonara |
| Supprimer la pizza carbonara | DELETE /pizzas/carbonara |
Par extension, une requête DELETE /pizzas correspondrait à "purger toutes les pizzas" (rarement implémenté)
