API Idempotence

The OCS.io solution implements all RESTful API as idempotent. The idempotence key is requestId which must be present in all POST/PUT/DELETE APIs.

Implemented Behavior

Following diagram depicts how Idempotent API is implemented in OCS.io:

Step	Actor	Action	Description
1.	External System	Send Request	External System sends Request to API exposed by OCS.io.
2.	OCS.io	Receive Request	OCS.io receives Request.
3.	OCS.io	Check Duplicity	OCS.io checks whether the Request is duplicated based on requestId.
4.	OCS.io	Fetch Response from History	If the Request is duplicated, OCS.io fetches the Response from History. Flow continues with Step 8.
5.	OCS.io	Request Validation	If the Request is not duplicated, OCS.io validates Request whether all mandatory attributes are populated, all data types are valid, ENUMs match with definition, etc.
6.	OCS.io	Perform Operation	If the Request is valid, OCS.io performs the Operation in the system.
7.	OCS.io	Prepare Response	OCS.io prepares Response with the result of the Operation. If Request was not valid, Response will be erroneous.
8.	OCS.io	Send Response	OCS.io sends Response back to External System.
9.	External System	Receive Response	External System receives the Response as handle it accordingly.

Step

Actor

Action

Description

External System

Send Request

External System sends Request to API exposed by OCS.io.

OCS.io

Receive Request

OCS.io receives Request.

OCS.io

Check Duplicity

OCS.io checks whether the Request is duplicated based on requestId.

OCS.io

Fetch Response from History

If the Request is duplicated, OCS.io fetches the Response from History. Flow continues with Step 8.

OCS.io

Request Validation

If the Request is not duplicated, OCS.io validates Request whether all mandatory attributes are populated, all data types are valid, ENUMs match with definition, etc.

OCS.io

Perform Operation

If the Request is valid, OCS.io performs the Operation in the system.

OCS.io

Prepare Response

OCS.io prepares Response with the result of the Operation. If Request was not valid, Response will be erroneous.

OCS.io

Send Response

OCS.io sends Response back to External System.

External System

Receive Response

External System receives the Response as handle it accordingly.

Example

For example, if External System calls by OCS.io exposed API createEntity on 1.10.2022 at 12:01:00 CET time with following payload:

{
  "requestId": "ID00-0000-0000-0001",
  "entityName": "Name of the Entity",
  "entityExternalId": "0001"
}

OCS.io creates the entity, system automatically generates Entity ID = 1, sets Entity Created Date to actual date and return response:

{
  "entityId": 1,
  "entityName": "Name of the Entity",
  "entityExternalId": "0001",
  "entityCreatedDate": "2022-10-01T12:01:00.000+02:00"
}

One minute later, External System wants to create another entity:

{
  "requestId": "ID00-0000-0000-0002",
  "entityName": "Name of the Entity",
  "entityExternalId": "0002"
}

OCS.io responses:

{
  "entityId": 2,
  "entityName": "Name of the Entity",
  "entityExternalId": "0002",
  "entityCreatedDate": "2022-10-01T12:02:00.000+02:00"
}

If from whatever reason External System repeats one minute later the first API call:

{
  "requestId": "ID00-0000-0000-0001",
  "entityName": "Name of the Entity",
  "entityExternalId": "0001"
}

OCS.io checks duplicity based on requestId and if duplicate Request is found, the original Response is returned:

{
  "entityId": 1,
  "entityName": "Name of the Entity",
  "entityExternalId": "0001",
  "entityCreatedDate": "2022-10-01T12:01:00.000+02:00"
}