Things you should know

POSTED 2 years ago

The purpose of this page is to detail the design principles, objects, behaviours and error handling for Chenosis APIs. The overriding goal of this portal is to enable all parties to implement Chenosis APIs in a flexible, yet consistent manner. We hope to achieve this by implementing the following principles:

  • Use of REST architectural principles and best practices.
  • Providing a set of well-defined objects that are abstracted from the underlying object representations held in the various Chenosis and partner systems. This allows an API client to construct an API message without requiring specific knowledge of the target server implementation.
  • Creation of a standard set of transaction types and other key enumerations, removing the need for developers to map for each and every API implementation.
  • Use of ISO international standards for enumerators such as currency and country codes.
  • Use of supplementary metadata and sub-types to enable use case specific properties to be conveyed where necessary.
  • Aligning our resource, entity and object implementations with existing industry guidelines from TM-Forum, GSMA and Open Mobile Alliance whenever possible.

Getting Started

Read the Get Started page which will show you how to Register and create an app.

Chenosis API supports two Authorisation mechanisms

Chenosis APIs currently have two authorisation mechanisms: API Key, and OAuth. Most of the Chenosis APIs use API Key today to support legacy apps, but is switching over to OAuth. Each API products page will specify what authorisation mechanisms each API uses.

  1. API Key uses the x-api-key header, which you can get from the apps section on your profile, under Consumer Key
  2. We use a standard OAuth 2.0 scheme for authorization. To make calls, check out our OAuth page to get information on implementing a 2-legged and 3-legged OAuth flow.

The API aims to be a RESTful resource

The Chenosis API endpoints attempt to conform to the design principles of Representational State Transfer (REST) Level 3. Chenosis APIS uses HATEOAS links in the response contents so that the client can easily discover and navigate the appropriate resource by traversing the hypermedia links.

JSON Conventions

Chenosis APIs use the JSON data format for responses (and in some cases, for requests), using the camelCase naming convention for fields. Chenosis API uses a JSON "data" envelope for most responses. The typical response of Chenosis APIs, including JSON and HATEOAS links are:

    "data": {
    "_links": {
        "self": {
            "href": "https://sanbox.api.chenosis.io/......"

The API is HTTP-based (over SSL)

Methods to retrieve data from the Chenosis API require a GET request. Methods that submit, change or destroy data require a POST. A DELETE request is also accepted for methods that destroy data. API methods that require a particular HTTP method will return an error if not invoked using the correct style. HTTP Response Codes are meaningful.

Sandbox area to play with the APIs

Chenosis APIs have a sandbox area on sandbox.api.chenosis.io where you can play with the API. It responds with dummy account data so you can interact with the API in a real way

Versions in the URL

Chenosis APIs use URI namespace versioning, like https://api.chenosis.io/v1/customers. For new and breaking changes, new versions will be released, and only 2 versions will be maintained. Versions older than n-1 will NOT be supported, and you will be required to change to a new version.

Various Client Headers are supported

For APIs that use API Keys for authorisation, clients must use the x-api-key header. Various other headers may also be required to be sent by clients - each APIs Product page lists the headers supported. Chenosis APIs support the transactionID header, generated and sent by the client, to allow for traceability. In most cases it's optional, but certain APIs require it in order to trace requests.

Synchronous and Asynchronous Operations and Headers

Chenosis API will respond synchronously with a HTTP 200 OK header for requests that can be immediately processed (like GET requests). Synchronous POST operations will result in the Chenosis API responding with a 201 Created, and a copy of the created object in the body. For certain other operations that require asynchronous processing (certain POST methods), Chenosis API will respond with a HTTP 201 Accepted Header to indicate an asynchronous response, containing a status object in the body.

Callbacks and polling

For asynchronous operations, certain APIs allow clients to either poll for the final response, or the Chenosis API Platform will callback to the clients end-point with the final result. Chenosis API does not support this client endpoint to have authentication enabled.

Caching is used to speed up certain responses

Certain APIs will return cached responses for data that does not change very frequently, in order to speed up responses

APIs are described using OpenAPI

Chenosis APIs are written and described using OpenAPI Specification version 2 (Swagger).

Encoding Standards

Chenosis APIs use E.123 format for telephone MSISDN numbers, and ISO 3166 format for country names and codes, and RFC 3339 for date/time fields

Customer Identities

Chenosis APIs use E.123 format for telephone MSISDN numbers, to identify a customer. Soon other mechanisms of Identity will be supported

Related documentation