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 negation in two ways:

  1. Clients can request a resource in a certain Media Type: JSON or XML.

  2. Clients can request a resource in a certain 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 clients sends a resource representation to HTTP API/IP in order to process it, it is mandatory to correctly set the media type.Without the media type, it is not possible for HTTP API/IP to process the request as it does not know the format of it.

The HTTP API/IP supports two media types:

  1. Recommended type: "application/vnd.oracle.insurance.resource+json".This type extends "application/vnd.oracle.resource+json" which in turns extends "application/json".

  2. "application/vnd.oracle.insurance.resource+xml".This type extends "application/vnd.oracle.resource+xml" which in turns extends "application/xml".

    Note

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

http://www.oracle.com/webfolder/technetwork/tutorials/appdevinfo/New REST Media Type.pdf

HTTP API/IP will return 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

Clients can set the media type using the "Accept" request header to inform HTTP API/IP about the media type they want the returned resource represented in.

  1. If "Accept" is not specified, but "Content-Type" is, "Accept" defaults to "Content-Type".

  2. If "Accept" is not specified, and "Content-Type" is not specified, "Accept" defaults to "application/vnd.oracle.insurance.resource+json".

  3. "Accept" = "application/vnd.oracle.insurance.resource+json" will return a resource in OHI JSON format.

  4. As a convenience: "Accept" = "application/json" will return a resource in OHI JSON format as well.

  5. "Accept" = "application/vnd.oracle.insurance.resource+xml" will return a resource in OHI XML format.

  6. As a convenience: "Accept" = "application/xml" will return a resource in OHI HTTP XML format as well.

Any other value for the "Accept" request header is incorrect. HTTP API will respond with HTTP Status Code "406".

Setting the Media Type for PUT/POST/PATCH requests

Clients have to set the media type as "Content-Type" request header to inform HTTP API/IP about the media type of the resource they send to HTTP API/IP.

  1. "Content-Type" set to "application/vnd.oracle.insurance.resource+json": HTTP API will process the incoming resource as OHI JSON.

  2. "Content-Type" set to "application/json": HTTP API will process the incoming resource as OHI JSON.

  3. "Content-Type" set to "application/vnd.oracle.insurance.resource+xml": HTTP API will process the incoming resource as OHI XML.

  4. "Content-Type" set to "application/xml": HTTP API will process the incoming resource as OHI XML.

Any other value or no value for the "Content-Type" request header is incorrect. HTTP API will respond with 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.

  1. if the "Accept-Language" is present,

    • 1. and has a valid value, use that value as the language. See below for valid values.

    • 2. but has no valid value, the value of the header is ignored.

  2. If "Accept-Language" is not present or not valid,

    • 1. use the language of the current user as set in the user preferences.

    • 2. 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 languages resource. Instead of the "_", a "-" should be sent. See table below for some examples:

languages.code Accept-Language Value

en

en

nl

nl

en__OHI

en—​OHI

pt_BR

pt-BR