IT | Utiliser les verbes HTTP dans une API

Bonjour internaute !

Ici, simplement quelques notes non exhaustives concernant l'utilisation des verbes HTTP pour une WebAPI.

 

Les verbes HTTP

Quelques infos à garder concernant les verbes HTTP

  • GET : Accède à une ressource (safe, idempotent)
  • HEAD : Accède aux métadonnées d’une ressource (safe, idempotent)
  • POST : Ajoute une ressource
  • PUT : Met à jour une ressource complète en la remplaçant par une nouvelle version (99% des cas) (idempotent)
  • PATCH : Met à jour une partie d’une ressource en envoyant un différentiel (une sorte de ‘git diff’)
  • DELETE : Supprime une ressource (idempotent)

Une requête est dite safe quand elle ne modifie pas une donnée sur le serveur.

Une requête est dite indempotente quand le fait de l'exécuter plusieurs fois de suite avec les mêmes données est identique à effectuer un seul appel.

 

Quelques remarques

1 - Pas de verbes dans les URI. S'il y a un verbe, c'est souvent qu'on utilise mal les verbes HTTP.

2 - Les URI sont à écrire en minuscules. Les noms de routes sont basées sur les ressources et pas sur les actions et il faut faire en sorte qu'elle soient compréhensibles mais synthétiques.

3 - A la création, si c'est le client qui gère la création d'ID, alors choisir PUT. Si c'est le serveur qui gère la création d'ID, privilégier un POST.

4 - Pas de POST ou PUT partiel : il y a PATCH pour cela.

5 - Eviter des requêtes PUT si il n'y a pas de requêtes équivalentes en GET.

6 - Utiliser GET pour des requêtes autres (calculs, appels divers, ...).

7 - Bien utiliser la notion de cache (creuser les notions de Last-modified, Cache-Control, Expires...)

8 - Ne pas mettre dans les URI des données qui devraient être en-têtes ou dans le corps.

9 - Choisir entre les routes en "/blabla/ressource" et "/blabla/ressource/" puis faire des redicrections 301 de la non-choisie vers la choisie.

 

Utiliser les bons codes retour

200 OK : fonctionne dans tous les cas.

201 CREATED : Indique qu'une ressource a bien été créée. A utiliser avec POST, voire PUT.

202 ACCEPTED : Requête acceptée pour traitement ultérieur. A utiliser dans le cas de requêtes asynchrones.

204 NO CONTENT : Indique que la requête s'est bien déroulée mais qu'aucune ressource n'est à retourner. A utiliser avec DELETE.

206 PARTIAL CONTENT : Indique qu'une réponse est incomplète.

400 BAD REQUEST : Pour les erreurs d'appels. A privilégier aussi en réponse par défaut quand aucun autre code de retour ne peut être utilisé.

401 UNAUTHORIZED : A utiliser quand le serveur a besoin de connaître le client pour accéder à sa requête et que ce dernier ne s'est pas authentifié.

403 FORBIDDEN : Quand le client, authentifié, n'est pas autorisé à accéder à la ressource demandée.

404 NOT FOUND : La ressource demandée n'est pas accessible.

405 METHOD NOT ALLOWED : L'appel d'une méthode n'a pas de sens ou l'utilisateur n'a pas le droit de faire cette demande.

406 NOT ACCEPTABLE : Problème de matching dans le header. A utiliser quand par exemple on souhaite accéder à une ressource XML alors que celle-ci est en JSON.

413 : REQUEST ENTITY TOO LARGE : La ressource est trop grande par rapport à ce que le serveur ou l'infra peut supporter.

418 : I'M A TEAPOT : et pourquoi pas ?

500 SERVER ERROR : Plantage côté server (la requête peut être tout à fait valide bien sûr).

 

 

Sources :

http://www.maxpou.fr/rest-crud/

https://blog.octo.com/designer-une-api-rest/

https://delicious-insights.com/fr/articles/meilleures-pratiques-pour-vos...

Zircon - This is a contributing Drupal Theme
Design by WeebPal.