APIs CMO API Key concepts

Products

Connectivity Management Orchestrator API (CMO API) is developed according to standards defined by TM Forum ®. The CMO API itself is an implementation of the “Product Inventory API” and the resource representation is based on the SID model. A central concept introduced by the model is the product.

A product is something that a customer purchased from a Telecommunications Service Provider. That could be for example a Connectivity package with data services, SIM card, usage volume limits and so on. That means the product represents something already available and CMO API allows customer IoT applications to manage their products. The Product is therefore the main resource that is manipulated by the CMO API, which essentially provides operations to search, retrieve and update product instances. Since CMO API is meant to cover the information related to IoT connectivity products, a number of specializations of the basic product concept are required to represent the different IoT product aspects that are supported in the CMO API. In this concept a product is taken as a base class and the actual resources retrieved are instantiations of specializations of the product as described in the section “Data Structures”.

Tenants

A tenant represents a space in the IoT Hub in which customer have access to their own data and services. Thus means each customer must have its own tenant in the T IoT Hub so that it can use any of the services provided by it. That also applies to CMO API. Each CMO API request is targeted to a tenant and in order for the request to be authorized the IoT application credentials shall be valid for that tenant. With help of the IoT Hub Tenant Management it can be configured to what Carrier’s IoT Platforms an T IoT Hub Tenant has access. The access permission of the user credentials used to login at the Carrier IoT Platform defines what Products can be accessed.

Tenants

Authentication

Authentication of CMO API request is based on a JWT Token (JSON Web Token), which is issued for a IoT application. For that the IoT application shall present the respective application credentials. API authentication is based on OAuth 2.0 and it used the client grant.

Communication Protocol

The CMO service interface is based on synchronous and asynchronous communication using a REST interface over https. Due to this architecture, any 3rd-party application acts as a client making requests.

Asynchronous external systems

  • Asynchronously working APIs of a 3rd-party applications will not perform the requested operation at once
  • This means that the result of an operation triggered by an API call is performed later (maybe overnight) and is not available after the response of the external system.
  • This means that all or only part of API calls provided by the external system will work in asynchronous mode
  • CMO API will signal to the customer by responding with appropriate HTTP status code that the communication mode from the external system is asynchronous
    • 202 accepted
    • operation accepted by the external system and will be executed later
  • Asynchronous operation has an ID and state of this operation could be tracked by separate API

Synchronous external systems

  • Synchronously working APIs of a 3rd-party application will perform the requested operation immediately
  • This means that the result of an operation triggered by an API call is performed immediately and is available after the response of the external system.
  • This means that all or only part of the API calls provided by the external system will be executed in synchronous mode
  • CMO API will signal to the customer by responding with an appropriate HTTP status code that the communication mode from the external system is synchronous:
    • 200 success
    • operation performed by the external system immediately

Monitor

It refers to the process of continuously measuring various aspects of a system, or operation to gather information and assess its performance. Monitoring plays a crucial role in ensuring the effective management and optimization. For CMO API, it is used to monitor the execution of requests on specific resource.

There are some differences between synchronous and asynchronous requests:

  • The result of a synchronous product update is returned immediately.
  • The result of an asynchronous product update is returned indirectly. Additional query to the monitor endpoint will provide the current state of asynchronous product update operation.
  • Whether a sync or async response is returned depends on the platform.

Task

A task represents a specific objective or action that needs to be accomplished within a defined timeframe. It can involve activities like service provisioning, network configuration, fault management, billing, customer support, or any other operational process. The CMO API is supporting several kinds of complex operations which are represented as a tasks.

The following Tasks supported by CMO API:

  • Batch Update Task - applies to multiple products update - asynchronous
  • Find Task - applies to search products by different kind of identifiers (product ID, SIM Card ICCID, Satellite terminal Serial Number) - synchronous
  • Terminate Asynchronous Process - applies to terminate already triggered asynchronous product update request - asynchronous