The RepresentationModel is a holder class that allows you to build a representation of a resource for a response. It contains properties that specify the resource state, embedded resources, collection members, links, headers, and other properties. If an endpoint needs to respond with a representation of the resource, create an instance of this class.

The RepresentationModel has a version property that allows the endpoint to specify the version number for the resource. If the version property is not set, the framework attempts to get the version from the RepresentationModel state, provided that the state is a RepositoryItem and the RepositoryItem has a version property. If the version number cannot be obtained from the RepresentationModel, the framework uses the ResourceVersionRepository to track version numbers. For more information, refer to the Working with Client-Side Caching section.

If an endpoint response is not a representation of a resource and does not require any HATEOAS support, the endpoint can return objects other than RepresentationModel. For example, the login endpoint responds with access token information by returning a Map. The JAX-RS Response class can also create a response.

The status code of a response defaults to 200 (ok) but you can customize response codes using the status method of the RepresentationModel. There are also utility methods for created and accepted status. Response headers can also be set using the header method of the RepresentationModel as well as add member to embedded collection resources.

Endpoints can also return a RepresentationModel object where a representation of the resource is transformed into the media type requested by the client. RepresentationModel should include the URI of any embedded sub-resources and let the payload schema configuration process determine if the sub-resource is returned in a representation response.

If the resource is a collection, then the member URIs of the resource should be added to the RepresentationModel.

When you add a definition to the relations registry, the RepresentationModel builds the relation name preceded with the relation definition key. For example:

RepresentationModel model = new RepresentationModel.Builder().state(order).links
    (Link.fromPath("/test/order/o12345").rel("oc:submitMyOrder"));