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