Influence Resource Representation

The default resource presentation can be influenced by several parameters. This is for example needed when an additional property is needed, or when a sub resource needs to be retrieved. The resource representation is controlled by parameters of the media type. For the media types, see Media Types

The HTTP API/IP Media types "application/vnd.oracle.insurance.resource+json" and "application/vnd.oracle.insurance.resource+xml" support 3 parameters that control resource representation:

1. "response" to get a minimal resource representation returned.

2. "expand" controls the inclusion of sub resources.

3. "fields" controls the inclusion of properties.

4. "aliases" controls the fields and expand list by adding possibility of using alias instead of the entire property name again and again.

5. "defaultoverride" overrides the default resource representation and will only return what is put in the "fields" parameter. Please note that "expand" parameter is ignored when "defaulttoverride" is used with value true.

The next sections describe those properties.

Minimal Response

In a machine-to-machine communication scenario, the client may not be interested in the resource representation of the created or updated resource. Knowing whether the response was processed successfully or not is sufficient to know. This can be determined using the HTTP status code. Sending the response costs server resources and network bandwidth. This overhead can be prevented by including parameter "response" in the Accept header.

Accept: application/vnd.oracle.insurance.resource+json; response=minimal

Currently, the "response" parameter supports only the value "minimal". When "response=minimal" is present, the "expand" and "fields" parameters are ignored.

The minimal response in JSON format:

{}

Include Sub Resources using "expand"

Sub resources can be included in the representation using the "expand" parameter. The following values are supported.

1. expand="<subresource 1>,<subresource 2>…​<sub resource n>". All the sub resources included in the list are added to the resource representation. For the sub resources, the default set of properties is included as described in the previous section.

2. expand="subResources", all sub resources of the next level are included.This is a shortcut for summing up all sub resource names of the next level.

3. expand="all": sub resources are included, including grand children, grand grand children etc.

For example, consider this structure:

claim
  claimLineList (sub resource)
    claimLineDiagnosesList (sub sub resource)
  claimDiagnosesList (sub resource)
  claimPendReasonList (sub resource)

The following table shows various possible usages of the "expand" parameter:

"expand" value	claimLine included?	claimLineDiagnosis included?	claimDiagnosis included?	claimPendReason included?
not specified	Only id, objectVersionNumber and link	No	Only id, objectVersionNumber and link	Only id, objectVersionNumber and link
"claimLineList"	Yes	Only id, objectVersionNumber and link	Only id, objectVersionNumber and link	Only id, objectVersionNumber and link
"claimLineList and claimDiagnosesList"	Yes	Only id, objectVersionNumber and link	Yes	Only id, objectVersionNumber and link
"claimLineList and claimLineList.claimLineDiagnosesList"	Yes	Yes	Only id, objectVersionNumber and link	Only id, objectVersionNumber and link
"subResources"	Yes	Only id, objectVersionNumber and link	Yes	Yes
"all"	Yes	Yes	Yes	Yes

When a certain level of (sub) resource has a next level, there are always links included to the next level. Whether more properties are included depends on the value of the "expand" parameter.

Include Dynamic Fields

The "expand" also impacts the inclusion of dynamic fields:

• If "expand" = "all", all dynamic fields are included.

• If "expand" includes "dynamicData", all dynamic fields of all expanded resources are included.

Include Dynamic Records

The "expand" also controls the inclusion of dynamic records:

• To include a dynamic record in the representation, give "expand" the value "<dynamicRecordFieldUsage>.

• If "expand" = "all", all dynamic records are included.

• If "expand" includes "dynamicData", all dynamic records of all expanded resources are included.

Consider this structure, where both claim and claimLine can have dynamic fields and records.

claim
  claimLineList (sub resource)

The following table shows how "expand" and "dynamicData" work together:

"expand" value	dynamic Fields/Records of claim shown?	dynamic Fields/Records of claimLine shown?
not specified	No	No
"dynamicData"	Yes	No
"claimLineList"	No	No
"claimLineList and dynamicData"	Yes	Yes
"subResources"	Yes	No

Include/exclude Properties

The "fields" parameter can be used to control which properties are to included in a resource representation. The "fields" parameter can control the included properties in root resource, in the sub resource and in the linked resource (only one level).

Consider the following default resource representation, when "fields" parameter is not used:

{
  "claim": {
    "id": 123,
    "code": "ABC",
    "totalClaimedAmount": 123.45,
    "brand": {
      "links": [
        {
          "href": "http://[hostName]:[portNumber]/[api-context-root]/generic/{referenceCollection}/{id}",
          "rel": "canonical"
        }
      ]
    },
    "claimLineList": [{
        "id": 123,
        "sequence": 1
      }, {
        "id": 124,
        "sequence": 2
      }]
  }
}

When "fields" has value "code|totalCoveredAmount|brand.code", the representation changes into:

{
  "claim": {
    "id": 123,
    "code": "ABC",
    "totalCoveredAmount": 123.45,
    "brand": {
      "links": [
        {
          "code": "brandCode"
          "href": "http://[hostName]:[portNumber]/[api-context-root]/generic/{referenceCollection}/{id}",
          "rel": "canonical"
        }
      ]
    },
    "claimLineList": [{
        "id": 123,
        "sequence": 1
      }, {
        "id": 124,
        "sequence": 2
      }]
  }
}

Note that:

1. Property "totalClaimedAmount" is gone, because it was not specified in the "fields" list.

2. Property "id" is not gone, it cannot be suppressed.

3. Property "code" is now included in the reference resource representation.

4. The properties of the claim line sub resource did not change. The "fields" property only impacts the resources that are present in its value. If no property of a resource is included in the "fields" value, the default representation is used.

For a linked resource, it is not needed to use the "expand" parameter. Specifying the "fields" parameter is sufficient. For example, to show the code of the message linked to a resource, just specify:

fields="message.code"

Properties Restrictions

For performance- and resource usage reasons, the "fields" parameter only influences linked resources of the first level. If a field is needed from a higher level resource, and additional request must be issued. So fields="payerCode.payer.code" does not include the Payer.code. There are exceptions to this rule for certain entities/references. For these exceptions, the fields can be fetched to more than 1 level also. These exceptions are:

• Person

• Country

• ClaimForm

• ServiceAddress

• RenderingAddress

• CountryRegion

• Provider:IndividualProvider and OrganizationProvider

Include Flex Code Properties

Additional flex code properties can be included using the "fields" parameter in the normal way:

<propertyName>.<flexCodeFieldUsage>

For example: Flex Code Definition "TARGET_GROUPS" has 3 Flex Code Field Usages:

1. Field "code" (Target Group Code), key

2. Field "description" (Target Group Description), descriptor

3. Field "size" (Target Group Size)

An entity has a property "group" of type flex code and uses Flex Code Definition "TARGET_GROUPS". In that case, in order to include "size", the "fields" expression should be:

fields="group.size"

Include/exclude Insurable Entity Properties

Properties of an insurable entity can also be included using the "fields" parameter:

fields="car.maximumSpeed"

This will include the maximumSpeed property of the insurable entity "car".

Use of alias

It is possible to use alias while mentioning properties in expand and fields sections. Use of alias can reduce the length of payload sent across if there are a lot of entries that need to be mentioned in the respective property. The syntax to use aliases is

aliases=<string1>^<alias1>|<string2>^<alias2>

Example: To fetch claim.code, claimLineList.code, claimLineList.coveredAmount, claimLineList.claimLineMessageList.message.code

aliases=claimLineList^cl|claimLineList.claimLineMessageList^clml
fields=code|cl.code|cl.coveredAmount|clml.message.code

Please note that it is possible to alias while mentioning aliases also.

Use of defaultoverride

The value of this parameter can be true or false, where false is the default.

Value false means current default behaviour of resource representation. Value true means, only return things that are asked in the fields/expand attributes, so no links, no id/objectVersionNumber, no details or references. All sought after attributes are required to be explicitly asked. Important things to note:

• If this parameter is used with value true, then expand parameter is ignored.

• If links are required at any level, they can asked by using keyword 'link'. See the example below.

• If the generic resource is altered using new attributes, then those are always included in the representation.

Example: Accept Header Parameter on Claims Resource:

Accept: application/json;defaultoverride=true;fields=id|code|claimLineList.code|link|claimLineList.link

This results in ONLY the following content in the payload

• claim.id

• claim.code

• claim.links

• claimLineList.code

• claimLineList.links