Concepts

HTTP API/IP uses RESTful principles. "The fundamental concept in any RESTful API is the resource. A resource is an object with a type, associated data, relationships to other resources, and a set of methods that operate on it".(Thoughts on RESTful API Design)

Resources can play different roles:

  • Singular versus Collection resources

  • Linked resources

  • Sub resource

See the following sections.

Singular versus Collection Resources

A singular resource exists "on its own". Examples are the claim with id=123, or the person with id=456 etc. Think of a singular resource as an object instance, or as a record in a database table.

Those singular resources can also be part of a collection resource. Examples of collection resources are all coverage labels or all persons with zip code 12345. Think of a collection resource as a set of objects, or all rows in a database table.

Linked Resource

Resources can be related to each other. For example, the claim with id=123 is claimed by a person with id=456. The resource representation of claim 123 is linked to the resource of person with id=456. In this example, the person resource is a linked resource.

Whether a resource is considered a linked resource depends on the use case. It is possible that a resource is a linked resource in one use case and a normal resource (not a linked resource) in another scenario.

Sub Resource

A resource representation may include details from another resource. For example: the resource for claim with id=123 can include details of all claim line resources of that claim. If the details of the claim lines are included in the resource representation directly, the claim line is said to be a sub resource.

An alternative implementation is to have multiple links from claim to all its claim lines. In that case, the claim lines are not sub resourced, but linked resources. Typically, OHI Components uses sub resources in those cases however.

Discoverability

A discoverable API enables its clients to explore the features of the API. This is one the key strengths of a RESTful API. Instead of relying on out-of-band documentation, the API is documenting itself by using HTTP features. HTTP API/IP support discoverability.

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

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

The response returned from the root URI will be like:

{
  "items": [
    {
      "name": "generic",
      "links": [
        {
          "rel": "canonical",
          "href": "http://[hostName]:[portNumber]/[api-context-root]/generic"
        }
      ]
    },
    {
      "name": "specific",
      "links": [
        {
          "rel": "canonical",
          "href": "http://[hostName]:[portNumber]/[api-context-root]/specific"
        }
      ]
    }
  ],
...
}

The response contains links to two other root resources:

  1. The item named "generic" has a link to the root resource of all HTTP API resources.

  2. The item named "specific" has a link to the root resource of all HTTP IP resources.

Evolvability

HTTP API and IP aim to be evolvable. Newer versions of OHI applications will contain HTTP API’s and/or IP’s with more or changed functionality. HTTP API/IP aim to deliver the new functionality in a non-breaking way. One way in which HTTP API / IP implements this, is by being forgiving. If for example, a property A1 is renamed to A2 in HTTP API/IP and the client software has not changed yet, the clients will keep sending property A1. HTTP API/IP will not raise an error about unknown property A1, but just ignore yet:

  • The same applies to sub resource names and dynamic record names. If a client uses an unknown name, no error is giving.

  • This also applies to property- and resource names used in parameters like "expand" and "fields" and identifiers used in OHI Query.

Incorrect values of a property are not ignored. So when property A can have values V1, V2 and V3 in release 1 and values V1, V2 and V4 in release 2, an error will be given when clients keep sending V3 to release 2. It is assumed that values may be entered by users and from user friendliness point of view, an error is required for an incorrect values. Incorrect property names are hard-coded in software and will be detected during client software testing.

Resource Identifier

Every resource has a URI as resource identifier. This guide shows URI’s in many examples. Those are just examples. No assumptions should be made about the structure of URI’s. HTTP API

Self Link

Resource representations can live outside the original HTTP conversation. Then can be transferred using mail, or stored on disk. In all those cases, it is important to know the URI of the resource representation. This URI is stored as a link with "rel"="self". All OHI Components resource representations include a "self" link. Following the "self" link will return the current representation of the same (set of) resource(s).

Fixed and Dynamic Elements

OHI Components are extendable. One can add dynamic fields to the already available fixed fields. Same goes for data collections: one can add dynamic records to the already available fixed data collections.

HTTP API treats fixed and dynamic elements in the same way. Clients need not know whether an element is a fixed, or a dynamic element.

Non Insertable or Non Updatable Elements

OHI resource fields that are not insertable or not updatable are dealt in the same way as unknown fields in the payload. If such fields are included in the payload, they are simply ignored. The metadata for the resource clearly defines all such fields that are not allowed to be part of Insert or part of Update.