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 client sends a resource representation to HTTP API/IP to process it, it is important 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 extends "application/json".

  2. "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.pdf

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.

  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" returns a resource in the JSON format.

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

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

  6. 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 error code "406".

Setting the Media Type for PUT/POST/PATCH Requests

You can set the media type in "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 processes the incoming resource as JSON.

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

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

  4. "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 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,

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

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

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

Table 1. Valid Languages
Language Code Accept Language Value

en

en

nl

nl

en__OHI

en—​OHI

pt_BR

pt-BR

Note

OHI supports a range of languages, categorized into two groups: Right-to-Left (RTL) languages, including Arabic and Hebrew, and Left-to-Right (LTR) languages, such as English, German, Spanish, and French, among others. All these languages are seeded. For a complete list, please refer to the "/api/generic/languages" resource.