APIs CMO API Understanding Synchronous and Asynchronous operations

This page provides an overview of the Connection Management Orchestrator (CMO) API, focusing on the differences between synchronous and asynchronous operations.

Synchronous request - In the API, calls for operations like activating a SIM card happen immediately. The client application sends the request and waits for an immediate response.
Asynchronous request - In the API, calls for operations like activating a SIM card receive a tracker ID. This tracker ID allows the user to track the operation’s progress while being processed in the background.

NOTE

Short summary:

  • Synchronous: Immediate response, 200 OK, and a modified product
  • Asynchronous: Monitor ID, 202 Accepted, and a monitor object

Here’s the table for MNO platforms that support the CMO API:

Platform NameSynchronous UpdatesAsynchronous Updates
TMSP✖✔
TMUS✔✖
INTELSAT:multiply :✔
IOTA✔✖
JASPER✔✖
AIRLINQ✖✔
1NCE✔✖
STC✖✔
TURKCELL✖✔
GALAXY1✖✔
NOTE
  • The operations listed below are available in the CMO API but may not be supported by all platforms. Here is page for more information about the supported features.

Synchronous operations

The following operations are considered synchronous:

  • Custom properties assignment
  • SIM card status update for platforms that provide synchronous activation ()

Synchronous operations are defined by the fact that the change is being applied immediately. The response type is 200 OK and the body contains the result of the operation. Here are two examples of synchronous operations responses:

  • SIM card activation
  • Custom properties assignment
{
  "id": "JASPER-899xxxxxxxxxxxxxxx47",
  "href": "<api_url>/TENANT/product/JASPER-899xxxxxxxxxxxxxxx47",
  "isBundle": true,
  "startDate": "2020-04-01T20:00:00.000Z",
  "status": "INACTIVE",
  ...
}

{
  "id": "JASPER-899xxxxxxxxxxxxxxx47",
  ...
  "customProperty": [
    {
      "name": "MyFavoriteColour",
      "value": "Blue"
    }
  ],
  ...

Asynchronous operations

The following operations are considered asynchronous:

  • SIM card status update for platforms that provide asynchronous activation
  • SIM card transfer for platforms that provide the transfer capability

Asynchronous operations has response type 202 Accepted and the response body consist of a monitor object. The monitor can be used to track the status of the operation. Here is the example of asynchronous operations responses:

  • Headers
  • Body
{
  "Link": "<https://{cmo_api_url}/{tenant}/monitor/{monitorId}>; rel="related"; title="monitor", <https://{cmo_api_url}/{tenant}/product/{productId}>; rel="self", <https://{cmo_api_url}/{tenant}/product/{productId}>; rel="canonical""
}

{
  "id": "{iccid}-1747918290-monitor",
  "href": "{cmo_api_url}/{tenant}/monitor/{iccid}-1747918290-monitor",
  "sourceHref": "{cmo_api_url}/{tenant}/product/{platformName}-{iccid}-simCard",
  "state": "IN_PROGRESS",
  "request": {
    "method": "PATCH",
    "body": [
      {
        "op": "replace",
        "path": "/status",
        "value": "SUSPENDED"
      }
    ],
    "headers": [
      {
        "name": "accept",
        "value": "application/json"
      },
      {
        "name": "content-type",
        "value": "application/json-patch+json"
      }
    ]
  },
  "response": [
    {
      "platform": "{platformName}",
      "statusCode": 200,
      "message": "",
      "state": "IN_PROGRESS",
      "body": {
        // ... platform specific response ...
      },
      "headers": [
        {
          "name": "Content-Type",
          "value": "application/json"
        }
      ]
    }
  ],
  "@type": "monitor",
  "errors": [],
  "correlationId": "08cf2679-a736-45bb-936d-7c00d1628f38"
}

Batch operations

Batch operations are a combination of synchronous and asynchronous operations. The response type is 202 Accepted and the response body consist of a monitor object, even if it only has synchronous operations. The monitor can be used to track the status of the operation. Here is the example of batch operations responses:

  • Headers
  • Body
{
  "Link": "<https://{cmo_api_url}/{tenant}/monitor/{monitorId}>; rel="related"; title="monitor", <https://{cmo_api_url}/{tenant}/product/{productId}>; rel="self", <https://{cmo_api_url}/{tenant}/product/{productId}>; rel="canonical""
}

{
  "id": "{iccid}-1747919425-monitor",
  "href": "https://{cmo_api_url}/{tenant}/monitor/{iccid}-1747919425-monitor",
  "sourceHref": "https://{cmo_api_url}/{tenant}/monitor/{iccid}-1747919425-monitor",
  "state": "IN_PROGRESS",
  "request": {
    "method": "PATCH",
    "body": {
      "productIdList": [
        "JASPER-{iccid}-simCard",
        "TMSP-{iccid}-simCard"
      ],
      "request": {
        "method": "PATCH",
        "body": [
          {
            "op": "replace",
            "path": "/status",
            "value": "SUSPENDED"
          }
        ],
        "headers": [
          {
            "name": "Content-Type",
            "value": "application/json-patch+json"
          }
        ]
      }
    },
    "headers": [
      {
        "name": "accept",
        "value": "application/json"
      },
      {
        "name": "content-type",
        "value": "application/json"
      }
    ]
  },
  "response": [
    {
      "platform": "JASPER",
      "statusCode": 200,
      "state": "DONE",
      "body": {
        ... platform specific response ...
      },
      "headers": [
        {
          "name": "Content-Type",
          "value": "application/json"
        }
      ]
    },
    {
      "platform": "TMSP",
      "statusCode": 200,
      "message": "",
      "state": "IN_PROGRESS",
      "body": {
        ... platform specific response ...
      },
      "headers": [
        {
          "name": "Content-Type",
          "value": "application/hal+json;charset=UTF-8"
        }
      ]
    }
  ],
  "@type": "monitor",
  "errors": []
}