Les instructions REST

Deadpool says hello

Situons

Récemment, j'ai eu une looongue discussion avec TnTakara sur le Discord de Grafikart concernant les verbes HTTP. Le discussion avait pour sujet la modification d'une ressource (au sens où REST l'entend).

Pour moi, depuis quelques années, voici mes croyances concernant l'utisation des verbes REST :

  • GET : Récupération d'une ressource
  • HEAD : OSEF MDR
  • POST : Création d'une ressource
  • OPTIONS : Le truc relou (OSEF MDR)
  • CONNECT : OSEF MDR
  • TRACE : OSEF MDR
  • PUT : Remplacement d'une ressource complète
  • PATCH : OSEF MDR
  • DELETE : Supprimer une ressource

Alors qu'en fait, c'est un peu plus compliqué que ça. Du coup pour clarifier la chose, je vais résumer l'intérêt des verbes REST. Bonne lecture !

Un peu d'histoire

Pour commencer, il est nécessaire de connaître trois choses :

  • La spécification RFC d'HTTP définit les verbes et leurs usages
  • REST est un style d'architecture défini dans le chapitre 5 de la thèse de doctorat de Roy Fielding et se base donc sur le protocole HTTP
  • PATCH est un verbe HTTP qui ne fait pas parti de la spécification initiale

Les verbes

GET

L'intérêt du verbe GET est connu de tous et sert à récupérer une ressource ou une collection de ressources.

Une requête HEAD permet de récupérer les entêtes qui seraient retournés par une requête GET sur la même ressource.

POST

Les requêts POST servent à deux choses notables :

  • Créer une ressource dans le cas où la requête est faite sur une collection
  • Modifier une ressource en envoyant uniquement la partie à modifier dans le cas où la requête est faite sur une ressource.

Ce dernier point est important parce'que la plupart des développeurs (moi y compris jusqu'à très très récemment) pensent que POST sert à créer une ressource et PUT à la modifier : non.

OPTIONS

Cette méthode sert à récupérer la configuration d'une route. Cette requête est automatiquement envoyée par le navigateur avant certains type de requêtes (typiquement avant les POST), pour s'assurer que la route accepte le POST qui va suivre.

CONNECT

Une requête CONNECT établit une connexion bidirectionnelle avec la ressource demandée. Notamment utilisée dans le cas où un site est chargé en HTTPS.

TRACE

La méthode TRACE demande simplement au serveur de retourner le contenu de la requête, pour vérifier ce qu'il a reçu.

PUT

La méthode PUT permet de remplacer totalement une ressource. Plus précisément, si j'envoie une requête PUT sur une ressource "/users/15", la ressource sera TOTALEMENT remplacée par le contenu de ma requête PUT.

PATCH

La requête PATCH est arrivé plus tard que ces comparses et elle est couramment mal utilisé. Je vous redirige sur cet article, en anglais, qui explique en détail les bons et les mauvais usages de PATCH.

DELETE

Comme pour GET, le nom de cette méthode ne laisse pas de place au doute : elle sert à supprimer une ressource ou une collection.

Conclusion

Ce qu'il faut retenir parce que c'est ce qui est très mal compris de manière générale c'est que :

  • POST permet de créer une ressource si appelée sur une collection, et de modifier partiellement une ressource si appelée directement sur une ressource
  • PUT permet de remplacer (modifier totalement) une ressource
  • PATCH ne s'utilise pas comme POST et PUT

Spongebob see ya

Xavier Stouder

Read more posts by this author.