Content Negotiation

Content negotiation refers to mechanisms defined as a part of HTTP that make it possible to serve different versions of a document (or more generally, representations of a resource) at the same URI.

HTTP API/IP does support content negotiation in the following two ways:

Clients can request a resource in a specific media type, for example, JSON or XML.
Clients can request a resource in a specific language, for example, English or French.

Media Type

The media type identifies the form of the data contained within a request or response message body. As such, the media type informs the client about the type and structure of the data it received. This also works the other way round. When a client sends a resource representation to the HTTP API/IP to process, it is essential to set the media type correctly. Without the media type, the HTTP API/IP cannot process the request because it does not know the format of the request.

The HTTP API/IP supports the following two media types:

Recommended type: "application/vnd.oracle.insurance.resource+json". This type extends "application/vnd.oracle.resource+json", which extends "application/json".
"application/vnd.oracle.insurance.resource+xml". This type extends "application/vnd.oracle.resource+xml", which extends "application/xml".

The media types "application/vnd.oracle.resource+json" and "application/vnd.oracle.resource+xml" are documented at New REST Media Type.

HTTP API/IP returns the media type of the response in the "Content-Type" response header for every resource representation it returns to the client.

Setting the Media Type for GET Requests

You can set the media type using the "Accept" request header to inform HTTP API/IP about the media type of the returned resource.

The following are a few scenarios:

If "Accept" is not specified but "Content-Type" is, "Accept" defaults to "Content-Type".
If "Accept" is not specified and "Content-Type" is not specified, "Accept" defaults to "application/vnd.oracle.insurance.resource+json".
"Accept" = "application/vnd.oracle.insurance.resource+json" returns a resource in the JSON format.
As a convenience: "Accept" = "application/json" returns a resource in JSON format as well.
"Accept" = "application/vnd.oracle.insurance.resource+xml" will return a resource in the XML format.
As a convenience: "Accept" = "application/xml" returns a resource in the Oracle Health Insurance HTTP XML format as well.

Any other value for the "Accept" request header is incorrect and results in an HTTP status code "406".

Setting the Media Type for PUT/POST/PATCH Requests

You can set the media type in the "Content-Type" request header to inform the HTTP API/IP about the media type of the resource they send to the HTTP API/IP.

The following are a few scenarios:

"Content-Type" set to "application/vnd.oracle.insurance.resource+json": HTTP API processes the incoming resource as JSON.
"Content-Type" set to "application/json": HTTP API processes the incoming resource as JSON.
"Content-Type" set to "application/vnd.oracle.insurance.resource+xml": HTTP API processes the incoming resource as XML.
"Content-Type" set to "application/xml": HTTP API processes the incoming resource as XML.

Any other value or no value for the "Content-Type" request header is incorrect and results in an HTTP status code "415".

Language

HTTP API/IP responses may contain translatable content. For example, the metadata resource returns the boilerplate labels, and other resources have translatable fields, like accessRestriction.name and many others.

HTTP API/IP selects the language as follows:

If the "Accept-Language" is present:
- And has a valid value, use that value as the language. See the following valid values.
- But has no valid value; the value of the header is ignored.
If "Accept-Language" is not present or not valid,
- Use the language of the current user as set in the user preferences.
- Use the default language if the current user has not set a preferred language.

In all situations, HTTP API/IP will set the Content-Language response header with the language code of the returned response.

Valid Languages

HTTP API/IP supports all languages defined in the "/api/generic/languages" resource. The value should match the code value of the language resource. Instead of the "_", a "-" should be sent. See the following table for some examples:

Table 1. Valid Languages
Language Code	Accept Language Value
en	en
nl	nl
en__OHI	en—OHI
pt_BR	pt-BR