Usage Notes

The intended use of this service is where there are multiple concurrent versions of a REST API, for backward compatibility of existing clients. The AcceptHeaderService allows the responsibility for content negotiation (determining which version of the REST API is to be used) to be performed by logic in the domain objects themselves.

The diagram below illustrated this:

acceptheaderservice

The REST request is submitted to a domain service with a nature of VIEW_REST_ONLY (MyRestApi in the diagram). This uses the AcceptHeaderService to obtain the values of the HTTP Accept header. Based on this it delegates to the appropriate underlying domain service (with a nature of DOMAIN so that they are not exposed in the REST API at all).

The service does not define any conventions as to the format of the media types. The option is to use the media type’s type/subtype, eg application/vnd.myrestapi-v1+json; an alternative is to use a media type parameter as a hint, eg application/json;x-my-rest-api-version=1 (where x-my-rest-api-version is the media type parameter).

Alternatives

As an alternative to performing content negotiation within the domain classes, the ContentMappingService SPI domain service allows the framework to perform the content negotiation responsibility.

The Restful Objects specification supports this with its own x-ro-domain-type media type parameter; this is used by the ContentMappingService to determine how to map domain objects to view models/DTOs.