Getting Started

When preparing your external system to use the platform REST API, the following are important to know:

• The platform must have a special user for your system to use in authenticating REST requests from this system.

• The external system must send a REST request using the Basic authentication method to generate a bearer access token that it will use later in other REST requests based on the Bearer authentication method.

Getting API Credentials

Get access to SimpleAPI and necessary parameters by completing these steps:

1. In your panel, go to Marketplace and search for SimpleAPI.

2. Subscribe to the found plan and wait for the order to complete.

3. In your home UX1 dashboard, click on the newly added menu item SimpleAPI, where you will get access to:

   • Base URL of the exposed endpoints is a URL prefix in all your requests and is not shown in the examples here.

   • Subscription key defines a subscription to API services that contains certain limits on the API usage, for example, it defines the upper limit on the number of requests your system can send per a period of time. Your system must send this key as the X-Subscription-Key custom header in every HTTP request.

   • Username is the login name to authenticate your system.

Token Generation

A bearer token must be used in all REST requests except for the token generation REST request. For the moment of the writing, a generated token is valid during a certain expiration period, which is 1500 s, that is, 25 min.

Note

If the system interacts with the platform permanently, it must periodically request the generation of the new token.

The POST request for a token must have the following HTTP headers:

• Content-type: application/json

• Authorization: Basic <credentials>

• X-Subscription-Key: <Your own subscription key>

Note

For integrations with other applications, you need to obtain the identifier from support and get pass it using the header X-Client-Id: <Your application identifier>.

The Authorization header in this request uses the Basic access authentication. Substitute the <credentials> placeholder with the base64 encoded login name and password pair. There are two ways to send this header:

• Prepare the base64 encoded “username:password” string and add the result to the Authorization header.

• Use a utility that accepts the username and password pair, prepares the Authorization header with the encoded credentials, and sends the request.

When using cuRL , the above two methods look as follows:

$ curl -X POST <base URL>/token \
  -H 'Authorization: Basic YWJh...JM3M5' \
  -H 'X-Subscription-Key: 066a6b...fd33b16' \
  -H 'Content-Type: application/json' \
  --data-raw '{"marketplace": "us"}'

$ curl -X POST <base URL>/token \
  -u cmp-api-username:cmp-api-password \
  -H 'X-Subscription-Key: 066a6b...fd33b16' \
  -H 'Content-Type: application/json' \
  --data-raw '{"marketplace": "us"}'

In the last method, you enter the user name and password pair instead of the Authorization header, which is generated by cuRL.

Note

Here and in the later examples, the encoded and encrypted strings are cut for brevity.

Throughout this documentation, the REST requests will be represented in the typical short format as in the following example:

POST /token HTTP/1.1
X-Subscription-Key: 066a6b...33b16
Authorization: Basic bXlBcGlMb...NTIwM1J6QTE=

If successful, the response must contain the bearer access token generated by the platform, for example:

HTTP/1.1 200 OK

{
  "token": "eyJwcm...0fQtrLk4RToj51HAmsRXO78",
  "expiresInSeconds": 1500
}

Testing the Bearer Token

Test the received bearer token in a REST request, for example, send a request to get a list of products:

GET /products HTTP/1.1
Authorization: Bearer eyJwcm...0fQtrLk4RToj51HAmsRXO78
X-Subscription-Key: 066a6b...33b16

The response must contain a list of all products, for example:

HTTP/1.1 200 OK

{
  "data": [
    {
      "mpn": "53fc25f7-6639-4f78-bb44-3c2dfec3ed40",
      "name": "Office 365 Extra File Storage",
      "serviceName": "O365",
      "minimumQuantity": "0.0",
      "maximumQuantity": "5000.0",
      "costs": [
         {
            "currency": "USD",
            "amount": "1.05",
            "type": "recurring"
         }
      ],
      "prices": [
         {
            "currency": "USD",
            "amount": "1.15",
            "type": "recurring"
         }
      ],
      "billingPeriod": {
         "type": "month",
         "duration": 1
      },
      "subscriptionPeriod": {
         "type": "month",
         "duration": 1
      },
      "dependsOn": [
        "91fd106f-4b2c-4938-95ac-f54f74e9a239"
      ]
    },
    {
      "mpn": "91fd106f-4b2c-4938-95ac-f54f74e9a239",
      "name": "Office 365 Enterprise E1",
      "serviceName": "O365",
      "minimumQuantity": "1.0",
      "maximumQuantity": "5000.0",
                          "costs": [
         {
            "currency": "USD",
            "amount": "17.5",
            "type": "recurring"
         }
      ],
      "prices": [
         {
            "currency": "USD",
            "amount": "19.8",
            "type": "recurring"
         }
      ],
      "billingPeriod": {
         "type": "month",
         "duration": 1
      },
      "subscriptionPeriod": {
         "type": "month",
         "duration": 1
      },
      "dependsOn": [ ]
    },
    { /* Other Products */ }
  ],
  "pagination": {
    "offset": 0,
    "limit": 10,
    "total": 11
  }
}

If the request was successful, you can proceed to use the REST API for other requests as described in the following documents of this set.

Pagination

The pagination section displayed in the previous example is returned in response to every GET request for a collection of objects. It indicates the position of a range of returned objects in the full collection discovered in the platform. The pagination structure contains three parameters:

• total: The total number of all items in the collection that meet the GET request.

• limit: The maximum number of the items that are returned in the response. A limit can be specified as a query parameter in a GET request. By default, it is 10.

• offset: The index of the first returned item (its position in the full collection). An offset can be specified as a query parameter in a GET request. By default, it is 0.

The following requests illustrate the above explanations:

• Return the first 10 or fewer items from the products collection:

  GET /products
  

• Return not more than 100 items starting from position 97:

  GET /products?offset=97&limit=100
  

Query Parameters

Along with pagination parameters mentioned in the previous section, API clients can use other query parameters as criteria to select certain objects from a specified collection. Each collection has its own query parameters. For example, the /orders collection enables you to use the customerId, status, and other order-specific parameters to retrieve the required orders. The following sample requires a list of orders related to the specified subscription and created after the specified date and time:

GET /orders?subscriptionId=1000054&creationTimeFrom=2019-12-11T17:32:28Z

The date and time are represented in the ISO-8601 UTC format.

Applying to Support

Every API response contains the X-Correlation-ID header that helps engineers to identify the internal transaction that operates the respective API call. When creating a trouble ticket on the support site, please include the X-Correlation-ID header value in your request.

Conclusion

From this document, you learned what data you must collect and what preparation steps you must go through to integrate your management system with the platform through the SimpleAPI. You know how to test whether your system is configured correctly for this API and how to use pagination and query parameters to request resource collections.

Previous Topic

Next Topic