Composite API Framework

Currently the API developers need to create multiple wrappers over the existing APIs to accomplish a particular functionality. To simplify this process, Icertis has designed a composite API framework that allows you to combine multiple single API endpoints and create a single response. The design of composite API framework is based on the existing API 2.0 model.

With single business API call, a developer can add unit of work type. For example, create new party record in party master (without approval workflow), use newly created party sysid and Name while creating agreement, and also add external or internal user in team of agreement.

Using composite API, the developer can create a composite request body for the following:

  • Create an agreement

  • Publish the agreement

  • Send the agreement for approval

The addition of composite APIs also gives Icertis a competitive business advantage.

Note: Presently, only up to five API calls can be included in a composite request.

Important Considerations

  1. Composite API is provided as an add-on feature over ICI APIs.

  2. Composite API will be based on request orchestrator and hence does not have any complex logic to handle logical scenarios like upsert.

  3. Moving one instance of agreement from one state to another is not supported in composite APIs framework.

  4. APIM quota limit will be applicable on sub-requests and not on the primary requests.

  5. Authentication validation is not a part of API Orchestrator, as individual base API like API 2.0 handle authentication and authorization separately.

Elements of composite API framework

Icertis has identified the following fundamental components of the composite API framework to meet business goals:

  • API endpoint for supporting composite structure

  • Request & Response representation

  • Validation framework for composition

  • Orchestration logic for composite requests [request execution]

  • Referencing field's structure & usage

Supported Workflows

Currently, composite API framework supports the following workflows:

  • Create multiple masterdata instances

  • Create masterdata and use it while creating agreement

  • Create agreement and associated documents (Inline Association)

  • Create user and add it to the agreement team

  • Create masterdata, and use it while creating agreement and add association (Peer/Parent-Child)

  • Create masterdata, and use it while creating agreement and team to agreement

All the above workflows are supported for Amendments as well.

Architecture

The composite API architecture is based on .NET core 6 Web API application. It will be deployed as containerized Azure application service that helps to combine multiple ICI API requests into a single request and execute them to perform a single unit of work.

The architectural flow diagram given below shows the flow of request from a tenant to ICI, and execution at API Orchestrator.

Picture

The descriptions of the flow points are as follows:

  • A: Composite request coming from Tenant App to APIM

  • B: Composite request redirects to Composite API from API

  • C: Composite API executes Sub-request 1

  • D: Sub-request 1 redirect to API-Endpoint 1

  • E: API Endpoint 1 returns response

  • F: Response of Sub-request 1 receives back to Composite API

  • G: Composite request executes sub-request n

  • H: Sub request n get redirects to API Endpoint n

  • I: API Endpoint n send a response back

  • J: Response of Sub-request n receives back to Composite API

  • K: Response of Sub-request 1 and Sub-request n combined into Composite response

  • L: Tenant receives Composite response

Use Case Scenario

Consider the following scenario to understand the implementation of composite API framework:

Objective: An API developer uses ICI entities via APIs to create a single composite request to perform various actions

Target Accomplishment: The developer will be able to:

  • Make a series of ICI REST API calls in a single API call

  • Use output of one call as an input for the next API call

  • Combine multiple subsequent request results in a single response body

The request and response call for the above scenario can be represented as shown below:

Request Representation

POST api/v2/composite

{

"composite-request": [

{

"method": "POST",

sequence: 1

url": "/agreements/ICMMSA/Create ",

"refId": newagreement",

"body": {"}

},

{

"method": "POST",

sequence: 2

url": /agreements/ICMMSA/associations/ICMSupportingDocument/",

"ref": newassociation",

"body": {parentId": "@{newagreement.sysid} .. data:{.}}

}

]

}

Response Representations:

{

"composite-response" : [{

"body" : {

"Messages": [],

"Data": [

],

"HasMoreData": false,

"PagingData": {

"RowsPerPage": 100,

"TotalNumberOfPages": -1,

"PageNumber": 1,

"TotalRowCount": -1

}

},

"httpHeaders" : {

"api-supported-versions": "1.0",

"cache-control": "no-cache",

"content-length": "1189",

"content-type": "application/json; charset=utf-8",

"date": "Tue, 26 Oct 2021 08:12:39 GMT",

"expires": "-1",

"pragma": "no-cache",

"strict-transport-security": "max-age=31536000",

"trackingid": "043823f9-5133-4f90-857a-00c2b208e67e",

},

"httpStatusCode" : 201,

"referenceId" : "newagreement"

},{

"body" : {

// all the response data

},

"httpHeaders" : {

// all headers

},

"httpStatusCode" : 201,

"referenceId" : "newassociation"

}]

}