Influence Resource Representation

Adding parameters to the request influences the resource representation and makes it easier to use and consume large results. By default, a server returns a default set of fields specific to a resource. You can use parameters to return the exact fields you need and control the amount of data that the server returns in a response. For example, when you want to view a subset of fields, instead of all the fields.

The request body of a generic search API supports the following parameters:

• "response" to return a minimal response.

• "expand" to include child resources.

• "fields" to include specific fields.

• "aliases" to add an alias to a field name.

• "defaultoverride" overrides the default resource representation and returns what you place in the "fields" parameter.

Please note that when using defaultoverride with the value true, ignores anything in the expand parameter.

Following is an example of using parameters in an HTTP request body to influence what a response displays:

POST http://[hostName]:[portNumber]/[api-context-root]/generic/persons/search

Body :

{
  "resource": {
    "q": "dateOfBirth.eq('1900-01-01').and.name.eq('Doe')"
  },
  "resourceRepresentation": {
    "fields": "officeAddress"
  }
}

Minimal Response

If you want to know whether your operation was successful - without the extra information about the response- you have an option for a minimal response. This minimal preference reduces the amount of data a request requires a server to send. Hence, it optimizes communication between the API caller and the server and is useful when communicating with limited bandwidth. It is at the discretion of the server to determine what constitutes a minimal response.

{
  "resource": {
    "q": "dateOfBirth.eq('1900-01-01')"
  },
  "resourceRepresentation": {
    "response": "minimal"
  }
}

The use of response=minimal ignores expand and fields parameters.

Minimal Response

{
    "offset": 0,
    "count": 3,
    "hasMore": false,
    "limit": 50,
    "items": [
        {
            "id": <id>,
            "code": "FN0052P0001",
            "createdBy": 2,
            "dateOfBirth": "1900-01-01",
            "dobInterpretation": "E",
            "functionDynamicLogicId": 40,
            "gender": "F",
            "lastUpdatedBy": 2,
            "name": "FN0052P0001",
            "objectLastUpdatedBy": 2,
            "objectVersionNumber": 1,
            "subtype": "PERS",
            "links": [
                       ....
                ]
        }

        {
            "id": 1587903,
            "code": "FI0009P0001",
            "createdBy": 2,
            "dateOfBirth": "1900-01-01",
            "dobInterpretation": "E",
            "functionDynamicLogicId": 40,
            "gender": "F",
            "lastUpdatedBy": 2,
            "name": "FI0009P0001",
            "objectLastUpdatedBy": 2,
            "objectVersionNumber": 1,
            "subtype": "PERS",
            "uuid": "33D637510A5930E6E0532332C40AE49A",
            "links": [
                ....
                ]
            },

        },
        {
            "id": 1792498,
            "code": "PO0034_1_2_2_RELA_002",
            "createdBy": 2,
            "dateOfBirth": "1900-01-01",
            "dobInterpretation": "E",
            "functionDynamicLogicId": 1132632,
            "gender": "F",
            "lastUpdatedBy": 2,
            "name": "Adam",
            "objectLastUpdatedBy": 2,
            "objectVersionNumber": 1,
            "subtype": "PERS",
            "uuid": "39eb1ec9-29b5-4576-af85-f0aad0bee8f1",
            "links": [
                         ....
                ]

        }
    ],
    "links": [
        {
            ...
        }
    ]
}

Expand

The expand parameter expands the root and child items in a hierarchy of a resource. The application supports the following values for the expand parameter:

• display child resources of all resources in a list:

  {
    "resource": {
      "q": "dateOfBirth.eq('1900-01-01')"
    },
    "resourceRepresentation": {
      "expand": "<subresource 1>,<subresource 2>...<subresource n>"
    }
  }

• expands all first-child resources of a resource:

  {
    "resource": {
      "q": "dateOfBirth.eq('1900-01-01')"
    },
    "resourceRepresentation": {
      "expand": "subResources"
    }
  }

• Expand all root and child resources in a hierarchy of resources:

  {
    "resource": {
      "q": "dateOfBirth.eq('1900-01-01')"
    },
    "resourceRepresentation": {
      "expand": "all"
    }
  }

For example, consider a hierarchy of resources:

claim
  claimLineList (first-level child resource)
    claimLineDiagnosesList (second-level child resource)
  claimDiagnosesList (first-level child resource)
  claimPendReasonList (first-level child resource)

displays the following results after using 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|claimDiagnosesList"	Yes	Only id, objectVersionNumber and link	Yes	Only id, objectVersionNumber and link
"claimLineList|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

If a resource has a child resource, any request to the resource displays links to the first-level child resources. You can use the expand parameter to display more details of a child resource.

Including Dynamic Fields

The use of expand parameter includes dynamic fields:

• The use of "expand" ="all" includes all dynamic fields of the resources and child resources.

• Including dynamicData keyword in your request includes all dynamic fields of the resource.

Not specifying any value to expand excludes all dynamic fields.

Including Dynamic Records

The use of expand parameter includes dynamic records:

• To view a specific dynamic record in the representation, you can add the value "<dynamicRecordFieldUsage> to expand.

• The use of "expand" ="all" includes all dynamic records of the resources and child resources.

• Including dynamicData keyword in your request includes all dynamic records of the resource.

Not specifying any value to expand excludes all dynamic records.

Consider the following data structure where both claim and claimLine have dynamic fields and records.

claim
  claimLineList (child resource)

The following table shows how expand and dynamicData work together:

Expand Value	Dynamic Fields or Records of Claim Shown?	Dynamic Fields or Records of ClaimLine Shown?
not specified	No	No
"dynamicData"	Yes	No
"claimLineList"	No	No
"claimLineList|dynamicData"	Yes	Yes
"subResources"	Yes	No

Fields

The fields parameter allows you to retrieve the exact fields you need over the default response for a resource.

The following is a sample response of a request without the fields parameter:

{
  "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
      }]
  }
}

Here is a response that uses the fields parameter with the "code|totalCoveredAmount|brand.code" value in the request. The response changes to:

{
  "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
      }]
  }
}

The following are the difference between the two responses:

• The totalClaimedAmount field is missing in the second one as we did not specify the field in the fields list.

• The id field is visible in both responses.

• The code field is visible in the second response.

• All the fields of the claim line (child resource) are present in both responses.

This means that the fields parameter shows the specific fields you specify in the request. The first response shows the default output for unspecified values for the fields parameter.

For a linked resource, the fields parameter works as the expand parameter.

The following code shows the code of a message for a resource:

{
  "resource": {
    "q": "dateOfBirth.eq('1900-01-01')"
  },
  "resourceRepresentation": {
    "fields": "message.code"
  }
}

Restrictions

The "fields" parameter only influences linked resources at the first level. So, "fields"="payerCode.payer.code" does not include the value for payer.code. Following are the entities that are exceptions to this rule:

• Person

• Country

• ClaimForm

• ServiceAddress

• RenderingAddress

• CountryRegion

• Provider:IndividualProvider and OrganizationProvider

• Premium Billing Allocation

• Commission Result Lines

• Activities and their subtypes (Global Activities/Financial Transaction Set Activities/Group Account Activities/Contract Activities)

Include Flex Code Fields

The fields parameter displays Flex Code fields in the following manner:

{
  "resource": {
    "q": "dateOfBirth.eq('1900-01-01')"
  },
  "resourceRepresentation": {
    "fields": "<propertyName>.<flexCodeFieldUsage>"
  }
}

Consider a Flex Code definition "TARGET_GROUPS" has three Flex Code field usages:

• A code (target group code) field, which is a key.

• A description (target group description) field.

• A size (target group size) field.

Consider a "group" flex code that uses the Flex Code definition "TARGET_GROUPS". To view the size field, the request body looks like this:

{
  "resource": {
    "q": "dateOfBirth.eq('1900-01-01')"
  },
  "resourceRepresentation": {
    "fields": "group.size"
  }
}

Include or Exclude Insurable Entities

The fields parameter shows the fields of an insurable entity. Following is a sample request body that shows the value of the maximumSpeed field of a car insurable entity:

{
  "resource": {
    "q": "code.like('BMW%')"
  },
  "resourceRepresentation": {
    "fields": "car.maximumSpeed"
  }
}

Aliases

You can give an alias to fields when using expand and fields parameters. Using an alias reduces the length of the payload when there are lots of entries in a request.

The syntax to use the aliases parameter is:

{
  "resource": {
    "q": "dateOfBirth.eq('1900-01-01')"
  },
  "resourceRepresentation": {
    "aliases": "<string1>^<alias1>|<string2>^<alias2>"
  }
}

Here is a request body that uses an alias to fetch claim.code, claimLineList.code, claimLineList.coveredAmount, and claimLineList.claimLineMessageList.message.code:

{
  "resource": {
    "q": "code.like('CLA%')"
  },
  "resourceRepresentation": {
    "aliases": "claimLineList^cl|claimLineList.claimLineMessageList^clml",
    "fields": "code|cl.code|cl.coveredAmount|clml.message.code"
  }
}

You can use an alias when using the aliases parameter.

Defaultoverride

This value of the parameter is true or false.

The false value returns the default response. The true value returns items you mention in the fields or expand parameters.

The response does not show any links, id, objectVersionNumber, details, or references.

If this parameter is true, the server ignores the expand parameter. Using the link keyword returns link to the resource. When altering generic resource using new attributes, then you need to include the attributes in the request body.

Here is a sample request to access claims resource:

{
  "resource": {
    "q": "code.like('CLA%')"
  },
  "resourceRepresentation": {
    "defaultoverride": "true",
    "fields": "id|code|claimLineList.code|link|claimLineList.link"
  }
}

This results in data for the following fields in the payload:

• claim.id

• claim.code

• claim.links

• claimLineList.code

• claimLineList.links

Exclude Reference Resources

The value of this parameter can be true or false, with false as the default value. When the excludereferenceresources is set to:

• false, returns the default response.

• true, all the reference resources and child lists are excluded from the response, except those mentioned in the fields and expand parameters.

All the fixed (non-referential) fields for the resources are returned by default. The excludereferenceresources can be used in conjunction with the fields and expand parameters (including dynamicData and subResources for expand parameter). If the defaultoverride parameter is true, the server ignores the excludereferenceresources parameter. With excludereferenceresources set to true, expanding a list resource does not automatically expand the child lists for that resource unless those are also part of the fields or expand parameters. Links to the resource are always returned as part of the response.

Here is a sample request to access claims resource:

{
  "resource": {
    "q": "code.like('CLA%')"
  },
  "resourceRepresentation": {
    "excludereferenceresources": "true",
    "fields": "claimForm.code",
    "expand": "claimLineList"
  }
}

This results in data for the following fields in the payload:

• All fixed (non-referential) fields and links for the claim resource.

• Code and links for claimform.

• All fixed (non-referential) fields and links for the claimline resource.