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
adds an alias to a field name. -
defaultoverride
overrides the default resource representation and returns what you place in thefields
parameter. -
excludereferenceresources
overrides the default resource representation and returns the direct fields, and the linked resources that you place in the fields, and the expand parameters.
Please note that when using defaultoverride
with the value true
, it 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|homeAddress"
}
}
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 the 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:
{}
Expand
The expand
parameter expands the root and child items in a hierarchy for 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 all resources:
{ "resource": { "q": "dateOfBirth.eq('1900-01-01')" }, "resourceRepresentation": { "expand": "subResources" } }
-
Expand all root and child resources in a hierarchy of all 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, |
No |
Only |
Only |
|
Yes |
Only |
Only |
Only |
|
Yes |
Only |
Yes |
Only |
|
Yes |
Yes |
Only |
Only |
|
Yes |
Only |
Yes |
Yes |
|
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 |
|
Yes |
No |
|
No |
No |
|
Yes |
Yes |
|
Yes |
No |
Improve API Performance by Switching from expand=all
to Specific Fields
We recommend specifying specific fields instead of using expand=all
in your API requests to improve performance.
This change can enhance efficiency and reduce unnecessary data retrieval.
Do the following steps to identify API calls that use the expand=all
and log them for analysis:
-
Enable detailed logging with a
POST
request togeneric/loggers/
with the following JSON payload:
{ "logger": "ExpandAllLogs", "logLevel": "TRACE", "duration": 200 }
This configuration will log API calls that use expand=all
for 200 minutes.
-
Review the logged data periodically to identify which API calls are using
expand=all
. -
Replace
expand=all
with specific fields in those API calls to optimize performance.
This proactive approach helps optimize your system’s performance by reducing unnecessary data retrieval and improving API response times.
Fields
The fields
parameter returns the fields you specify in a request.
As an alternative to the default response, adding the fields
parameter returns the exact fields you specify in the request with the parameter.
The id field is present in every response, regardless of the field being mentioned in the fields parameter.
|
The following code returns the code of a message resource:
{ "resource": { "q": "dateOfBirth.eq('1900-01-01')" }, "resourceRepresentation": { "fields": "message.code" } }
You can use the bar symbol (|) to specify multiple fields.
The following is a request that uses the fields
parameter for multiple values:
{ "resource": { "q": "code.eq('ABC')" }, "resourceRepresentation": { "fields": "code|totalCoveredAmount|brand.code" } }
The response to the above request:
{
"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 is a response to 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
}]
}
}
Compare the two responses to see the effect the fields
parameter has on the request:
-
The
totalClaimedAmount
field is absent in the first response as the request did not specify thetotalClaimedAmount
field in thefields
list -
The
code
of the brand is present only in the first response.
All the fields of the claim line (child resource) are present in both responses and the id
field is always present.
The two responses show that when you use the fields
parameter in a request, the response contains only the specified fields.
The request returns the default representation of a resource if you include nothing in the fields
section.
The fields
parameter works as the expand
parameter for a linked resource.
Restrictions
The fields
parameter only influences linked resources at the first level.
So, using "fields"="payerCode.payer.code"
in a request does not return the value of payer.code
.
The following entities are exceptions to this rule and have expandable linked resource implementation:
-
Person
-
Country
-
ClaimForm
-
ServiceAddress
-
RenderingAddress
-
CountryRegion
-
ServiceDefinition
-
ProductServiceDefinition
-
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).
-
Macros (Bulk update definition and dynamic logic)
-
Locationtypegroups
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 insurable car 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 payload length when there are many 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.
|
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 andexpand
parameters.
|
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.
Exclude Links
To exclude the links of the reference fields and child lists from the response, set the parameter exclude links
to true
in the request body.
By default, all the operational links are returned.
Request Payload with excludelinks
Attribute
Following is an example payload to set exclude links
to true
:
{
"resource": {
"q": "code.like('CLA%')"
},
"resourceRepresentation": {
"excludereferenceresources": "true",
"fields": "claimForm.code",
"expand": "claimLineList",
"excludelinks": true
}
}
The response results in data for the following fields, which are requested in the payload:
-
All the fixed fields and links for claims resources.
-
id
and code forclaimForm
. -
All fixed fields for the
claimline
resource.
|
Response with Operational Links Present at the Child List
In some cases, operational links are present within the child lists of the requested main resource data.
- For example:
-
When the pend reasons for a claim have not yet been resolved in the claims resource, the claimpendreason resource will have a resolve link attached to the child list object.
When exclude links
is set to true
, and
-
If the request payload does not request the respective child list with operational links, then no data with respect to the child list is returned by the response.
-
The request payload requests some data under the child list; the response returns the operational links along with the requested data.
When any reference field or a child list data is requested through the request payload with excludelinks parameter set to true , it returns only the links that are requested in the payload; however, the id field of the reference property or the child list property aways returns in the response body.
|