Representation Profile (Mixin)
Resources that accept
PATCH requests may or may not return a representation in the response. The client might want the response returned, however, to save a subsequent
GET request, or to omit a returned representation to save transmission time. The Representation profile gives a client the ability to specify that they prefer the created or modified representation returned with the response or omitted from the response.
Resources that support the Representation profile include the Representation profile header in its list of profile headers.
The client sends a
prefer: return=representation header indicating that they want the content of the representation returned with the response. This header saves them from having to issue a
GET request to fetch the state. The resource returns a status of
200 OK instead of
204 No Content for
PATCH operations. In the case of a
POST response, the
location header will be omitted. Instead, the response will have a
content-location header that indicates the URI for the full representation.
Some profiles (see Action and Lookup) use the
POST operation and return a redirect status code such as
307 along with a
location header that the client follows to retrieve the resource. When a resource implements the Representation mixin, and the client sends
prefer: return=representation in their request, the resource will return the resource representation instead of a redirect status.
Prefer header parameter
return also accepts the value
minimal which tells the resource to return no representation and instead return the normal status code for that resource operation.
POST operations will add the appropriate
HTTP/1.1 Semantics and Content: RFC 7231
content-location: section 188.8.131.52
- 200 OK: section 6.3.1
- 201 Created: section 6.3.2
- 204 No Content: section 6.3.5
location: section 7.1.2
prefer Header for HTTP: RFC 7240
- return=representation / return=minimal: section 4.2
© 2019-2023 Matt Bishop
This work is licensed under a Creative Commons Attribution-NoDerivatives 4.0 International License.