Default Resource Representation (GET)

The resource representation is the representation of a resource that is exchanged between client and server in REST. So when the client sends a GET to a HTTP API resource, the resource representation is returned. The same happens with POST, PUT and PATCH: the client sends a resource representation to the HTTP API resource URI and HTTP API will update the resource based on the information present in the resource representation.

The resource representation differs between collection and singular resources. The resource representation sent to clients (after a GET operation) and the representation sent by clients (in a PUT, POST, PATCH operation) are very similar, but there are a few differences. The next sections describe the resource representation returned by GET operations. The differences in the representation used by PUT, POST and PATCH are described in the sections that handle those operations.

GET Representation of a Collection Resource

A collection resource is represented like this:

{
   "offset" : "0",
   "count" : "8",
   "hasMore" : false,
   "limit" : "200",
   "items" : [ {<resource 1 representation>
   },{<resource 2 representation>
   },{<resource 3 representation>
...
   },{<resource 8 representation>
   } ]
   "links" : [<collection resource links>]
}

  1. The representation starts with the pagination properties, like "offset". See the xref: http-api-ip-concepts/pagination.adoc[Pagination] sections for details.

  2. The resources themselves are present as values in the "items" array. Their representation matches the representation of a singular resource.

  3. The representation ends with the links section. The table below describes the possible link relations for a collection resource.

Link relations for a collection resource:

rel href Example

self

Link to the collection resource itself (includes all query arguments)

"http://[hostName]:[portNumber]/[api-context-root]/generic/claims?limit=50&orderBy=code&q=code.like('CLA%25')&offset=50&fields=code"

next

Link to the next set of resources if present (includes all query arguments)

"http://[hostName]:[portNumber]/[api-context-root]/generic/claims?limit=50&orderBy=code&q=code.like('CLA%25')&offset=100&fields=code"

prev

Link to the previous set of resources if present (includes all query arguments)

"http://[hostName]:[portNumber]/[api-context-root]/generic/claims?limit=50&orderBy=code&q=code.like('CLA%25')&offset=0&fields=code"

GET Representation of a Singular Resource

A singular resource is represented like this:

{
   "<resource name in singular>" : {
      "<property 1>" : <value 1>,
      "<property 2>" : <value 2>,
...
      "<property n>" : <value n>,
      "<reference property 1>" : <value 1>,
      "<reference property 2>" : <value 2>,
...
      "<reference property n>" : <value n>,
      "links" : [<resource links>],
      "<sub resource 1>" : [],
      "<sub resource 2>" : [],
...
      "<sub resource n>" : []
  }
}

  1. Properties: the basic properties of the resource, for example "code".

  2. Reference properties: the properties of the resource that reference a related resource. For example: the brand of a claim. Brand is a resource itself.

  3. Links: the link relations for the singular resource.

  4. Sub resources: the sub resources that are nested inside the singular resource representation.

The next sections give more details about the different pieces of the representation.

GET Representation of Properties

The properties of an object can be found in the View Objects page. Object properties in Oracle Health Insurance Components can have different data types. Each datatype has a different representation which is defined in the section xref: http-api-ip-concepts/property-representation-(get).adoc[Property Type Representation].

Not all properties in the View Objects page need to be present in the resource representation. Technical properties are not included. Technical properties do not have a functional meaning for clients. They are processed by internal Oracle Health Insurance algorithms which clients should not touch. For example, the "claim" resource has a technical property "blockedByProcessing".

The property name of a resource property matches the name in the View Objects page: for fixed properties, just the name is used. For dynamic properties, the Field Usage Name is used as property name.

As defined in the Concepts section, resources can either be collection resources, singular resource or linked resources. Which properties are included by default in the representation depends on the role of the resource. See the table below:

Element Included In Collection Resource Included in Singular Resource Included in Linked Resource

Basic Properties (single value)

Default

Default

No

Reference Properties (single value)

Default

Default

No

Dynamic Record (single value)

No

No

Never

Sub resources

Links only

Links Only

Never

Basic Properties (multi value)

Default

Default

Never

Reference Properties (multi value)

Default

Default

No

Dynamic Record (multi value)

No

No

Never

Basic Properties (time valid)

No

No

Never

Reference Properties (time valid)

No

No

Never

Dynamic Record (time valid)

No

No

Never

Explanation:

  • "Default": the element is included in the resource representation by default, but can be excluded.

  • "No": the element is not included in the resource representation by default, but can be included.

  • "Never" the element is not included in the resource representation by default, and can not be included.

  • "Links only": only id, objectVersionNumber and a resource link are included by default. The other properties can be included using "expand" or "fields" (see xref: http-api/influence-resource-representation.adoc [Influence Resource Representation]

    Note

    In the table above, with "properties" both dynamic fields and fixed fields are meant. Note however that by default dynamic fields are not included. See Influence Resource Representation how to include them.