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

Collect the following parameters before you start using the API:

Base URL of the exposed endpoints is a URL prefix in all your requests and is not shown in the examples here.
Username is the login name to authenticate your system.
Password is the password to use for getting an access token as described in the next section.

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>

The Authorization header in this request uses 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.

The POST request for a token must also include a JSON Body containing the marketplace parameter with the value of the reseller’s marketplace. You can get the code from the Reseller control panel URL, for example, https://portal.cloudnet.services. In this example, the code is us and this is the code which a US reseller must specify, while a reseller from the United Kingdom would specify uk.

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

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

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

JSON

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=

JSON

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
}

JSON

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

JSON

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
  }
}

JSON

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.

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
```
JSON
Return not more than 100 items starting from position 97:
```
GET /products?offset=97&limit=100
```
JSON

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

JSON

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 Marketplace API. 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.

Getting API Credentials

Token Generation

Testing the Bearer Token

Pagination

Query Parameters

Applying to Support

Conclusion