PUT

Utilisation

Une requête PUT demande au serveur de stocker la représentation incluse à l’URI indiquée. Si la ressource existe déjà, le serveur remplace la totalité de son état par la nouvelle représentation. Si aucune ressource n’existe à cette URI, le serveur en crée une.

Idempotence

PUT est idempotent. Envoyer plusieurs fois la même requête PUT produit le même état du serveur que l’envoyer une seule fois. Cela contraste avec POST, où des soumissions répétées créent des ressources en double ou déclenchent plusieurs fois le traitement.

L’idempotence rend PUT sûr à réessayer après une défaillance réseau. Un client qui ignore si une requête précédente est arrivée peut la renvoyer sans risquer d’effets de bord indésirables.

Négociation de contenu

Le serveur valide la représentation entrante au regard de ses propres contraintes. Lorsque le Content-Type correspond aux attentes et que le contenu est bien formé, le serveur stocke la ressource et répond 201 Created pour les nouvelles ressources, ou 200 OK / 204 No Content pour les remplacements.

Lorsque le type de média est incompatible, le serveur renvoie 415 Unsupported Media Type. Une réponse 409 Conflict indique un conflit d’état sans rapport avec le type de contenu, comme une version qui ne correspond pas.

PUT vs POST

POST délègue le traitement à la ressource cible. PUT indique l’URI exacte à laquelle la représentation appartient. Un PUT sur /articles/42 stocke l’article à /articles/42. Un POST sur /articles demande à la collection de créer un nouvel article à une URI choisie par le serveur.

PUT vs PATCH

PUT remplace la ressource entière. PATCH applique des modifications partielles. Mettre à jour un seul champ avec PUT impose d’envoyer la représentation complète. PATCH n’envoie que les changements.

Créer une ressource

Un client stocke un fichier texte brut à /docs/setup.txt. Le serveur crée la ressource et répond 201 Created.

Requête

PUT /docs/setup.txt HTTP/1.1
Host: api.example.re
Content-Type: text/plain
Content-Length: 24

Install, configure, run.

Réponse

HTTP/1.1 201 Created
Location: /docs/setup.txt
Content-Length: 0

Remplacer une ressource

Un client remplace une ressource JSON existante à /users/42. Le serveur confirme la mise à jour avec 200 OK et renvoie la représentation stockée.

Requête

PUT /users/42 HTTP/1.1
Host: api.example.re
Content-Type: application/json
Content-Length: 43

{"name":"Alice","email":"alice@example.re"}

Réponse

HTTP/1.1 200 OK
Content-Type: application/json
Content-Length: 51

{"id":42,"name":"Alice","email":"alice@example.re"}

Mise à jour conditionnelle

Une requête conditionnelle utilisant If-Match empêche d’écraser une ressource modifiée par un autre client. La valeur d’ETag garantit que la mise à jour ne s’applique qu’à la version attendue.

Requête

PUT /config/app.json HTTP/1.1
Host: api.example.re
Content-Type: application/json
If-Match: "a1b2c3"
Content-Length: 27

{"debug":false,"port":8080}

Réponse

HTTP/1.1 204 No Content
ETag: "d4e5f6"

CORS

Les requêtes PUT multi-origines déclenchent toujours une vérification préalable CORS. Le navigateur envoie d’abord une requête OPTIONS pour confirmer que le serveur autorise PUT sur la ressource cible.

Codes de statut de réponse

201 Created indique que le serveur a créé une nouvelle ressource à l’URI cible. Cela s’applique lorsqu’aucune ressource n’existait auparavant à cet emplacement.

200 OK confirme qu’une ressource existante a été remplacée et que la réponse contient la représentation mise à jour dans son corps.

204 No Content confirme un remplacement sans corps de réponse. C’est courant lorsque le client n’a pas besoin qu’on lui renvoie la représentation stockée.

412 Precondition Failed indique que la condition If-Match n’a pas été satisfaite. La valeur d’ETag fournie par le client ne correspond pas à la version actuelle de la ressource : le serveur rejette donc la mise à jour pour éviter d’écraser des modifications faites par un autre client.

409 Conflict signale un conflit d’état au niveau applicatif, sans rapport avec les préconditions, comme un conflit de fusion de contenu ou une collision de gestion de versions que le client doit résoudre manuellement.