1. HTTP (Hypertext Transfer Protocol)

  1. HTTP Methods

  1. PUT method
    1. Writing requests (clients)
    2. Reading requests (servers)
    3. Idempotentcy
    4. Overview table
    5. See also

PUT method

The PUT method updates a resource with an uploaded document, creating it if it doesn't exist.

Writing requests (clients)

Clients should use PUT. If the same operation can be made with a PATCH request, use that instead (retrying the request with PUT if the server does not support it).

Reading requests (servers)

The server should dereference the request-URI, then test the conditional request headers against the result. If the resource conditional headers test false, return 412 (Precondition Failed). If the resource does not exist, attempt to create it.

The server may validate the uploaded document to be stored. If the uploaded resource is the wrong media type, the server may convert the resource to an acceptable media type, or return 415 (Unsupported Media Type)

Commit the resource to storage. If the server had to create the resource to fill this request, return 201 (Created). Otherwise, return 200 (OK).

The "selected representation" is considered to be the document being uploaded by the user-agent. If the server has saved the uploaded document exactly, the response may contain ETag and Last-Modified headers. If the server normalizes the contents of the document in any way (for example, collapsing whitespace), then you cannot include these headers.

If the Prefer request-header lists return=representation, then return the contents of the document as it would be returned in a subsequent GET request. This is useful if the server normalizes the document, and the client needs to know how the document was normalized.

If Prefer lists return=minimal, then return a zero-length body on success, including Content-Length: 0.

Otherwise, write a description of the changes made to the server.

Idempotentcy

PUT is idempotent, in the sense that two requests back to back is the same as one request. However, the second request can still change server state if a third party made a separate modification in between the requests.

Overview table

Name
PUT
Description
Save a resource to the target location.
Conditional fail
412 Precondition Failed
Request payload
Permitted
Response payload
Permitted
Cachable
Never
Specification
RFC 5789: Hypertext Transfer Protocol (HTTP/1.1): Semantics and Content. 4.3.4. PUT

See also