
:Notice: Licensed to the Apache Software Foundation (ASF) under one or more contributor license agreements. See the NOTICE file distributed with this work for additional information regarding copyright ownership. The ASF licenses this file to you under the Apache License, Version 2.0 (the "License"); you may not use this file except in compliance with the License. You may obtain a copy of the License at. http://www.apache.org/licenses/LICENSE-2.0 . Unless required by applicable law or agreed to in writing, software distributed under the License is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR  CONDITIONS OF ANY KIND, either express or implied. See the License for the specific language governing permissions and limitations under the License.



== 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:

image::refguide:applib-svc:reference-services-api/acceptheaderservice.png[width="700px"]

The REST request is submitted to a domain service with a xref:refguide:applib:index/annotation/DomainService.adoc#nature[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).

[TIP]
====
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 xref:refguide:applib:index/services/conmap/ContentMappingService.adoc[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 xref:refguide:applib:index/services/conmap/ContentMappingService.adoc[ContentMappingService] to determine how to map domain objects to view models/DTOs.
