AcceptHeaderService

This service simply exposes the HTTP Accept header to the domain.

Its intended use is to support multiple versions of a REST API, where the responsibility for content negotiation (determining which version of the REST API is to be used) is managed by logic in the domain objects themselves.

API

AcceptHeaderService.java

interface AcceptHeaderService {
  List<MediaType> getAcceptableMediaTypes()     (1)
}

1	getAcceptableMediaTypes() The intention is that this service only returns a list when the request is initiated through the Restful Objects viewer.

Members

getAcceptableMediaTypes()

The intention is that this service only returns a list when the request is initiated through the Restful Objects viewer.

Otherwise the service will likely return null.

Implementation

The Restful Objects viewer provides an implementation of this API, AcceptHeaderServiceForRest.

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:

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.