Customizing Resource Representations

Provides information about Customizing Resource Representations.

It is recommended that RESTful web services provide a way for clients to customize the resource representations transferred by the server in order to optimize the response payload or the number of requests needed to retrieve the representations of linked resources. Resource representations may be customized by applying various constraints such as expanding resource hypermedia links and embedding representations of linked resources, excluding or selectively including certain resource fields. Link expansion and field inclusion or exclusion can be applied for both instance and collection resources, in case of a collection resource the same constraints must be applied for each instance resource embedded in the collection. The constraints represent expressions over the fields of a resource, in case the expression implies field inclusion or hypermedia link expansion the expression may be recursively defined following the hierarchy of linked resources or using wild cards. Representation constraints may be defined via the request contextual information such as query parameters or HTTP headers. It is recommended that information for the applied representation constraints is included in responses containing customized resource representations.

Customizing Representations using HTTP Headers

Different representations may be identified via a custom header, thus decoupling the serialization from the concrete format of the resource. The same custom header may be included in both requests and responses. Furthermore, if a custom header is used we will have a more fine-grained model for specifying exactly which links or fields we need to be included if not all of them.

Here are several suggestions for custom headers:

Header	Description
X-Representation-Expand	The header defines a list of linked resources that need to be included in the representation as well. The value of the parameter shall be a comma separated list of the names of the fields that are links to resources which representations need to be included, * denotes expansion of all links in the resource. If the links included for expansion contain other links that the client wishes to expand as well, then the expansion expression can be recursively defined using concrete links, ** denotes recursive expansion of all links, e.g X-Representation-Expand: properties(metadata),operations(),references or X-Representation-Expand: *. In case the link points to resources of the same type as the target resource then the same expansion constraints are applied for expanded and embedded resources. In case the link points to a collection resource the expansion may be further constrained via resource pagination, e.g. X-Representation-Expand: references(offset:0, limit:30). If the entities represented by the target resources implement a hierarchical structure and the link for expansion points to a subset of the hierarchy then the expansion can be further parametrized with a depth argument specifying the depth of the search, e.g. X-Representation-Expand: references(depth:5) or X-Representation-Expand: subgroups(depth:-1).
X-Representation-Exclude	The header will define a list of resource fields that need to be excluded from the representation. The value of the header shall be a comma separated list of field names which need to be excluded. A rule can be set to apply the same excludes for embedded entities of the same type, e.g. functional item references must be represented with the same excludes that apply for the root functional item resource requested.
X-Representation-Include	The header defines a list of resource fields that will be selectively included in the representation, fields from the default resource representation which are not listed here will be excluded. The value of the of the parameter shall be a comma separated list of the names of the fields which will be included to the representation of that resource, * denotes inclusion of all fields from the resource. If the fields included represent expandable links to resources which fields the client wishes to selectively include as well, then the inclusion expression can be recursively defined using concrete field names, ** denotes recursive inclusion of all fields, e.g X-Representation-Include: properties(name,value,metadata()),name,id or X-Representation-Include: properties(*),name,id. If other constraints like X-Representation-Exclude or X-Representation-Expand are present, they are not taken into account. In case the resource's field is link and points to resources of the same type as the target resource then the same inclusion constraints are applied for included resources. In case the resource's field is link and points to a collection resource the inclusion may be further constrained via resource pagination, e.g. X-Representation-Include: references(offset:0, limit:30). If the entities represented by the target resources implement a hierarchical structure and the resource's field link for inclusion points to a subset of the hierarchy then the inclusion can be further parameterized with a depth argument specifying the depth of the search, e.g. X-Representation-Include: references(depth:5) or X-Representation-Include: subgroups(depth:-1).

Customizing Representations Using Query Parameters

Different representations may also be identified in the resource URI, e.g via using query parameters. This approach shares the advantages of the one above regarding decoupling the serialization from the concrete format of the resource and fine granularity but, on the other hand, mixes representation with business constraints by defining the requested customization in the URI.

Here are several suggestions for query parameters:

Parameter	Description
expand	The query parameter defines a list of linked resources that need to be included in the representation as well. The value of the parameter shall be a comma separated list of the names of the fields that are links to resources which representations need to be included, * denotes expansion of all links in the resource. If the links included for expansion contain other links that the client wishes to expand as well, then the expansion expression can be recursively defined using concrete links, ** denotes recursive expansion of all links, e.g expand=properties(metadata),operations(),references or expand=*. In case the link points to resources of the same type as the target resource then the same expansion constraints are applied for expanded and embedded resources. In case the link points to a collection resource the expansion may be further constrained via resource pagination, e.g. expand=references(offset:0, limit:30). If the entities represented by the target resources implement a hierarchical structure and the link for expansion points to a subset of the hierarchy then the expansion can be further parametrized with a depth argument specifying the depth of the search, e.g. expand=references(depth:5) or expand=subgroups(depth:-1).
exclude	The query parameter will define a list of resource fields that need to be excluded from the representation. The value of the parameter shall be a comma separated list of field names which need to be excluded. A rule can be set to apply the same excludes for embedded entities of the same type, e.g. functional item references must be represented with the same excludes that apply for the root functional item resource requested.
include	The query parameter defines a list of resource fields that will be selectively included in the representation, fields from the default resource representation which are not listed here will be excluded. The value of the of the parameter shall be a comma separated list of the names of the fields which will be included to the representation of that resource, * denotes inclusion of all fields from the resource. If the fields included represent expandable links to resources which fields the client wishes to selectively include as well, then the inclusion expression can be recursively defined using concrete field names, ** denotes recursive inclusion of all fields, e.g include=properties(name,value,metadata()),name,id or include=properties(*),name,id. If other constraints like exclude or expand are present, they are not taken into account. In case the resource's field is link and points to resources of the same type as the target resource then the same inclusion constraints are applied for included resources. In case the resource's field is link and points to a collection resource the inclusion may be further constrained via resource pagination, e.g. include=references(offset:0, limit:30). If the entities represented by the target resources implement a hierarchical structure and the resource's field link for inclusion points to a subset of the hierarchy then the inclusion can be further parametrized with a depth argument specifying the depth of the search, e.g. include=references(depth:5) or include=subgroups(depth:-1).