Search Results
  1. HTTP (Hypertext Transfer Protocol)
  1. HTTP Preferences
  1. Prefer: return
    1. return=representation
    2. return=minimal
    3. Writing requests (clients)
    4. Reading requests (servers)
    5. Overview table
    6. Syntax
      1. Example

Prefer: return

The "return" preference can modify how a server responds to a successful operation.

Many methods specify that the request specify the result of the action, for example, a table of resources modified. Some servers also offer the option to omit this result, or to return the affected resource. Using a return preference offers a standard way to specify this behavior.

return=representation

The return=representation preference requests the server send the complete contents of the affected resource, along with a Content-Location header specifying the URI of that resource.

Clients should be careful handling URI references, which might resolve differently under the request URI instead of the canonical resource URI. Clients should update the internal representation using the returned resource, and resolve URI references from the internal representation.

return=minimal

The return=minimal preference requests the server send an empty body upon a successful response. This should be 204 No Content, but can also be 200 OK with a zero-length body.

Writing requests (clients)

Different uses of this preference may be chosen depending on the client and need.

Clients making a PATCH request may prefer to send return=representation to verify the result of the operation is what they expect.

Clients in an automated script might not care about result of the operation, and send return=representation.

Reading requests (servers)

Servers will need to ignore this preference based on the specifics of the operation. This preference does not make sense applied to safe operations.

This preference only applies to successful results. In the event of an error, normal error handling (returning a document describing the error) should be followed.

Overview table

Name
return
Description
Indicates what the server write to the response message body.
Specification
RFC 7240: Prefer Header for HTTP

Syntax

return = "return" BWS "=" BWS ("representation" / "minimal")

Example

POST /collection HTTP/1.1
Host: example.org
Content-Type: text/plain
Prefer: return=minimal

Upload body