PUT

Syntaxe

Paramètres

Description

Cette méthode permet d'ajouter ou d'effectuer un envoi complet d'une ressource sur le serveur Web.

Remarques

• La méthode PUT demande que l'état de la ressource cible soit créé ou remplacé par l'état défini par la représentation incluse dans la charge utile du message de requête. Un PUT réussi d'une représentation donnée suggère qu'un GET ultérieur sur cette même ressource cible entraînera l'envoi d'une représentation équivalente dans une réponse 200 OK. Cependant, rien ne garantit qu'un tel changement d'état sera observable, car la ressource cible pourrait être traitée par d'autres agents utilisateurs en parallèle, ou pourrait être soumise à un traitement dynamique par le serveur d'origine, avant la réception de tout GET ultérieur. Une réponse réussie implique uniquement que l'intention de l'agent utilisateur a été atteinte au moment de son traitement par le serveur d'origine.
• Si la ressource cible n'a pas de représentation actuelle et que le PUT en crée une avec succès, le serveur d'origine doit en informer l'agent utilisateur en envoyant une réponse 201 Created. Si la ressource cible a une représentation actuelle et que cette représentation est modifiée avec succès conformément à l'état de la représentation incluse, le serveur d'origine doit envoyer une réponse 200 OK ou 204 No Content pour indiquer la réussite de la requête.
• Un serveur d'origine devrait ignorer les champs d'entête non reconnus reçus dans une requête PUT (c'est-à-dire, ne pas les enregistrer dans le cadre de l'état de la ressource).
• Un serveur d'origine devrait vérifier que la représentation PUT est cohérente avec toutes les contraintes du serveur pour la ressource cible ne pouvant pas ou ne seront pas modifiées par le PUT. Cette situation est particulièrement important lorsque le serveur d'origine utilise des informations de configuration internes liées à l'URI afin de définir les valeurs des méta-données de représentation sur les réponses GET. Lorsqu'une représentation PUT n'est pas cohérente avec la ressource cible, le serveur d'origine devrait soit les rendre cohérentes, en transformant la représentation ou en modifiant la configuration de la ressource, soit répondre avec un message d'erreur approprié contenant des informations suffisantes pour expliquer pourquoi la représentation est inadaptée. Les codes d'état 409 Conflict ou 415 Unsupported Media Type sont suggérés, ce dernier étant spécifique aux contraintes sur les valeurs de type de contenu. Par exemple, si la ressource cible est configurée pour toujours avoir un Content-Type: de type «text/html» et que la représentation en cours PUT a un Content-Type: de «image/jpeg», le serveur d'origine doit effectuer l'une des actions suivantes :     reconfigurer la ressource cible pour refléter le nouveau type de média; transformer la représentation PUT dans un format cohérent avec celui de la ressource avant de l'enregistrer en tant que nouvel état de ressource; ou, rejeter la requête avec une réponse 415 Unsupported Media Type indiquant que la ressource cible est limitée à «text/html», y compris peut-être un lien vers une ressource différente étant une cible appropriée pour la nouvelle représentation.
• Le HTTP ne définit pas exactement comment une méthode PUT affecte l'état d'un serveur d'origine au-delà de ce qui peut être exprimé par l'intention de la requête de l'agent utilisateur et la sémantique de la réponse du serveur d'origine. Il ne définit pas ce qu'est une ressource, dans n'importe quel sens de ce mot, au-delà de l'interface fournie via HTTP. Il ne définit pas comment l'état des ressources est entreposé, ni comment un tel entreposage peut changer à la suite d'un changement d'état des ressources, ni comment le serveur d'origine convertie l'état des ressources en représentations. De manière générale, tous les détails de mise en oeuvre derrière l'interface de ressource sont intentionnellement masqués par le serveur.
• Un serveur d'origine ne doit pas envoyer un champ d'entête de validateur, tel qu'un champ ETag: ou Last-Modified:, dans une réponse réussie à PUT, sauf si les données de représentation de la requête ont été enregistrées sans aucune transformation appliquée au corps (c'est-à-dire, la ressource les nouvelles données de représentation sont identiques aux données de représentation reçues dans la requête PUT) et la valeur du champ de validation reflète la nouvelle représentation. Cette exigence permet à un agent utilisateur de savoir quand le corps de représentation qu'il a en mémoire reste à jour à la suite du PUT, donc n'a pas besoin d'être récupéré à nouveau à partir du serveur d'origine, et que le ou les nouveaux validateurs reçus dans la réponse peut être utilisé pour de futures requêtes conditionnelles afin d'éviter des écrasements accidentels.
• La différence fondamentale entre les méthodes POST et PUT est mise en évidence par l'intention différente pour la représentation jointe. La ressource cible dans une requête POST est destinée à gérer la représentation incluse selon la propre sémantique de la ressource, tandis que la représentation incluse dans une requête PUT est définie comme remplaçant l'état de la ressource cible. Par conséquent, l'intention de PUT est idempotente et visible pour les intermédiaires, même si l'effet exact n'est connu que du serveur d'origine.
• Une interprétation correcte d'une requête PUT suppose que l'agent utilisateur sait quelle ressource cible est souhaitée. Un service sélectionnant un URI approprié au nom du client, après avoir reçu une requête de changement d'état, devrait être mis en oeuvre en utilisant la méthode POST plutôt que PUT.
• Si le serveur d'origine n'effectue pas le changement d'état PUT demandé vers la ressource cible et souhaite à la place l'appliquer à une ressource différente, par exemple lorsque la ressource a été déplacée vers un URI différent, le serveur d'origine doit envoyer une réponse 3xx approprié (Redirection); l'agent utilisateur peut alors prendre sa propre décision concernant la redirection ou non de la requête.
• Une requête PUT appliquée à la ressource cible peut avoir des effets secondaires sur d'autres ressources. Par exemple, un article peut avoir un URI pour identifier la version actuelle (une ressource) étant distincte des URI identifiant chaque version particulière (différentes ressources qui à un moment donné partageaient le même état que la ressource de la version actuelle). Une requête PUT réussie sur l'URI de la version actuelle peut donc créer une nouvelle ressource de version en plus de changer l'état de la ressource cible, et peut également entraîner l'ajout de liens entre les ressources associées.
• Un serveur d'origine autorisant PUT sur une ressource cible donnée doit envoyer une réponse 400 Bad Request à une requête PUT contenant un champ d'entête Content-Range:, car la charge utile est susceptible d'être un contenu partiel ayant été par erreur mis en tant que représentation complète. Les mises à jour de contenu partielles sont possibles en ciblant une ressource identifiée séparément avec un état chevauchant une partie de la plus grande ressource, ou en utilisant une méthode différente ayant été spécifiquement définie pour les mises à jour partielles (par exemple, la méthode PATCH).
• Les réponses à la méthode PUT ne peuvent pas être mises en cache. Si une requête PUT réussie passe par un cache ayant une ou plusieurs réponses entreposées pour l'URI de demande effective, ces réponses entreposées seront invalidées.