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:
-
Clients can request a resource in a certain Media Type: JSON or XML.
-
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:
-
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.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.
-
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 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.
-
"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 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 below for 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 languages resource. Instead of the "_", a "-" should be sent. See table below for some examples:
Language Code | Accept Language Value |
---|---|
en |
en |
nl |
nl |
en__OHI |
en—OHI |
pt_BR |
pt-BR |