HTTP API Resources

Root Resource

All available HTTP API resources can be discovered from the HTTP API root URI:

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

The response contains links to all collection resources supported by the Oracle Health Insurance Component, like this:

{
  "items" : [
    {
      "name" : "<collection resource name>",
      "links" : [
        {
          "rel" : "canonical",
          "href" : "http://[hostName]:[portNumber]/[api-context-root]/generic/<collection resource name>"
        },
        {
          "rel": "describedBy",
          "href": "http://[hostName]:[portNumber]/[api-context-root]/generic/<collection resource name>/metadata"
        }
        {
          "rel": "oi:definition",
          "href": "http://[hostName]:[portNumber]/[api-context-root]/generic/<collection resource name>/definition"
        }
      ]
    }
...
repeated for each collection resource
...
  ],
  "links" : [
    {
      "rel" : "self",
      "href" : "http://[hostName]:[portNumber]/[api-context-root]/generic"
    }
  ]
}
Warning

It is recommended for clients to find the resource URL for the collection they need, based on the "name". The "name" value is stable across releases, while href’s can change.

Most (not all!) Objects present in the View Objects, have a corresponding resource. Typically, the resource name is just the plural of the object name in the View Objects page. When in doubt, the resource name can be retrieved from the "resources" resource:

/[api-context-root]/generic/resources?q=basedOnEntity.eq('<object name from View Objects page>')

Technical objects are not exposed as resources. The View Objects page does show those objects, but there is no corresponding resource. Examples of technical objects are ActivityBucket and Enrollment.

Link Relations

As shown above, three different links are available in the root resource representation for each collection resource:

  1. "canonical", to be used to retrieve the actual collection resource in order to execute the functionality.

  2. "describedBy": to be used to retrieve metadata about the collection resource. This returns the full OpenAPI specification of the API.

  3. "oi-definition": as HTTP API delivers CRUD like functionality, the HTTP URL’s and HTTP methods are similar for the different API’s. What is different though is the object the HTTP API works on. Clients can retrieve the definition object right away by following this link, without having to retrieve the full OpenAPI specification.

Collection Resource

The collection resource contains a set of singular resources. The properties of the singular resources are returned in the collection resource, together with a link to the singular resource.

The URL for a collection resource is structured as follows:

http://[hostName]:[portNumber]/[api-context-root]/generic/{resource name}

An example of a representation of a collection resource (details omitted):

{
  "items" : [
    {
      "id" : 10,
      "code" : "P1",

... more properties ...

      "links" : [
        {
          "href" : "http://[hostName]:[portNumber]/[api-context-root]/generic/persons/10",
          "rel" : "canonical"
        }
      ]
    },
    {
      "id" : 20,
      "code" : "P2",

... more properties ...

      "links" : [
        {
          "href" : "http://[hostName]:[portNumber]/[api-context-root]/generic/persons/20",
          "rel" : "canonical"
        }
      ]
    }
  ],
  "links" : [
    {
      "href" : "<URI to self>",
      "rel" : "self"
    }
  ]
}
Note

By default Included as properties are all single valued properties, including all references to related resources. Not included by default are sub resources and multi-valued fields. This is done to keep responses small by default. The default behavior can be extended using the "fields" or "expand" parameter.

Singular Resource

The URL for a singular resource is structured as follows:

http://[hostName]:[portNumber]/[api-context-root]/generic/{resource name}/{id}

where <resource name> is the name of the collection resource in plural.

Insurable Entity Resources

Every insurable entity type will be exposed as a separate collection and singular resource automatically. The name of the resource is defined in the Insurable Entity Types page (FN0063). The resource properties and dynamic records of an insurable entity resource are completely driven by the insurable entity definition.

The URI of the collection resource for an insurable entity type is:

http://[hostName]:[portNumber]/[api-context-root]/generic/{insurableEntityType.resourceName}

The URI of the singular resource for an insurable entity type is:

http://[hostName]:[portNumber]/[api-context-root]/generic/{insurableEntityType.resourceName}/{id}

Flex Codes Resource

The "flexCodes" resource has some special functionality: the properties returned match the flex code definition of the flex code.

http://[hostName]:[portNumber]/[api-context-root]/generic/{resource name}/{id of the flexcode}

If this flex code for example is for a flex code definition with flex code field usages "code", "displayName" and "active", the flex code resource representation will look like:

{
    "id": ,
    "objectVersionNumber": <object version number>,
    "code": "<code>",
    "displayName": "<display Name>",
    "active": true,
    "links": [
      {
        "href": "http://[hostName]:[portNumber]/[api-context-root]/generic/{resource name}/{id of the flexcode}",
        "rel": "self"
      }
    ]
  }