Operations Overview and Concepts

HTTP API Operations

Following table shows the different operations HTTP API resources support and how they are mapped to HTTP methods:

Operation	HTTP Method	DB Operation (SQL)
Create(Insert)	POST	Insert
Update (Modify)	PUT	Update
Patch	PATCH	Insert/Update/Delete
Delete (Remove)	DELETE	Delete
Collection Patch(Change multiple rows)	PATCH	Insert/Update/Delete
Read (Retrieve)	GET	Read/Find

Not all resources support all methods. Certain resources may be read-only for example. This applies to "super-types": both organization and person are sub types of the super type "relation". The super type resource "relations" only supports GET. The other methods that are only supported on the sub-type level.

When a HTTP method is called upon a resource that does not support that method, HTTP status code 405 is returned.

Discoverability

One can detect which operations are supported on a resource by retrieving the resource information from the "resources" resource.

Example request:

/[api-context-root]/generic/resources?q=collectionName.eq('<name of the collection>')

The response will contain properties like supportsPOST, supportsDELETE etc.

It is also possible to call the OPTIONS method on the resource. HTTP API will return the supported methods as part of the HTTP Response Headers like this:

200 OK
Allow: GET,PUT,OPTIONS

This means the resource only supports retrieve (GET) and update (PUT).

HTTP API Sub Resource Handling

The resource representation to be processed by an HTTP API operation, may also include sub resources. In general, those sub resources will be processed as well. However:

1. If the sub resource is not present in the OHI RESOURCE table, it is ignored silently.

2. If the sub resource is present in the OHI RESOURCE table but does not support the HTTP API operation, it is ignored silently.

HTTP API Property Handling

During PUT, PATCH and POST, the resource properties are processed as well. There are a some special cases though:

1. Technical properties. Technical properties are not included in a GET response. If a client does include a technical property in a PUT, POST or PATCH payload, they are ignored silently.

2. "transactionSource" and "referenceCode" are handled identical to technical properties.

3. A fixed list of properties is always read only: id, uuid, createdBy, creationDate, lastUpdatedBy, lastUpdatedDate, sourceCreatedBy, sourceCreationDate, sourceLastUpdatedBy, sourceLastUpdatedDate, createdByDataSet, lastUpdatedByDataSet, createdByEnvironment, lastUpdatedByEnvironment and objectVersionNumber. When those properties are included in the payload of PUT, POST or PATCH, they are ignored.

4. The subtype property is never updatable. When this property is included in the payload of PUT or PATCH, it is ignored.

5. Resource specific property restrictions. Those will be explained in the sections that describe individuals HTTP methods.

Media Type

When invoking an operation, clients typically send a resource representation they want HTTP API to process. HTTP API needs to know the type of the content the client is sending. It is therefore mandatory to set the media type in the Content-Type header. More details can be found in the section Media Types.

Operations Response Representation

POST, PUT and PATCH will return the created/modified resource in the default representation as described in section Default Resource Representation (GET). Clients can also influence what is returned by using any of the options described in section Influence Resource Representation

Concurrency Control

Both PUT and PATCH operation update existing resources. Concurrency Control defines what happens if multiple customers change the same resource simultaneously. Consider user A querying a resource and just after that user B is querying the same resource. Both A and B make a change. B now saves. Is A allowed to save as well, potentially overriding the changes made by B?

HTTP API is using optimistic locking to prevent this scenario. Every resource representation holds an object version number.

See table below where both A and B manipulate an artificial resource R with one property: ("<value>", n) means: the resource R has value "<value>" and the object version number is n.

Action	User A Resource	User B Resource	Server Resource
Initial status			"A", 1
GET by A	"A", 1		"A", 1
GET by B	"A", 1	"A", 1	"A", 1
Local change by A	"B", 1	"A", 1	"A", 1
Local change by B	"B", 1	"C", 1	"A", 1
PUT/PATCH by B (successful)	"B", 1	"C", 1	"C", 2
Resource returned to B after PUT/PATCH	"B", 1	"C", 2	"C", 2
PUT/PATCH by A (failed)	"B", 1	"C", 2	"C", 2

The PUT/PATCH by user A fails because the object version number passed by A (1) does not match the number at the server (2). User A has to re-execute a GET to get hold of a fresh resource and re-do his change.

HTTP API and IP use "Opt-in concurrency control". If clients do not include the object version number in the resource, HTTP API/IP will NOT enforce optimistic locking but assume the change must be applied regardless of the version. Clients are responsible to pass in object version numbers with correct values if they want optimistic locking to be enforced by HTTP API/IP.

Validation and Error Handling

During any operation, HTTP API will execute the Oracle Health Insurance business rules to validate the incoming data. When any rule is violated, the whole incoming message is discarded and an error response is returned. HTTP will execute all business rules and report all errors back at once.

Multiple error details are returned as part of the response only for business rule/ Functional errors in Oracle Health Insurance application. For errors related to DB/ unmarshalling errors, only the first encountered error is returned as part of the response

The Content-Type header is set to "application/vnd.oracle.resource+json;type=error" (or application/vnd.oracle.resource+xml;type=error)

The error response in JSON looks like:

{
  "o:errorDetails": [
  {
    "o:errorCode": "<OHI Error code>",
    "title": "OHI error message"
    "o:errorPath": <errorPath>
  }
  ]
}

An example, with 2 errors:

{
  "o:errorDetails": [
  {
    "o:errorCode": "OHI-DYLO-L004",
    "title": "The diagnosis code \"1234\" is not compliant with its definition"
    "o:errorPath": "$"
  },
  {
    "o:errorCode": "GEN-RULE-002",
    "title": "This \"Diagnosis\" must have at least one \"Diagnosis Setting\""
    "o:errorPath": "$"
  }
  ]
}

The "title" contains the error message in the language of the user using HTTP API.

The error response in XML looks like:

<?xml version="1.0" encoding="UTF-8"?>
<exceptionDetail xmlns:o="http://www.oracle.com/insurance/exception" title="ExceptionTitle" type="ExceptionType">
   <o:errorDetails>
      <o:errorDetail o:errorCode="OHI-ERR" title="Title" o:errorPath="errorPath"/>
   </o:errorDetails>
</exceptionDetail>