General information

In this article:

Introduction

The ActivePlatform application programming interfaces (APIs) are defined in the REST style based on HTTP 1.1 [RFC2616] and provide access to resources (data entities) via URL paths. Each request operates via Hypertext Transfer Protocol (HTTP) and makes it easy to use with any programming language.

Audience

This document is intended for research and development engineers who integrate ActivePlatform with external services (online store, provisioning services, and other external systems).
Readers should be familiar with the basic ActivePlatform concepts (see Terms and Definitions) and Operator Control Panel.

Documentation conventions

Basic concepts

REST API allows using the following standard HTTP methods: GET, PUT, POST, PATCH, and DELETE (see HTTP request methods). Request and response message bodies use the JavaScript Object Notation (JSON) format. API responses are encoded with UTF-8.

In a method description, {base_url} is a path parameter for the URL of the ActivePlatform installation (for example, https://test.activeplatform.com).

Authorization and authentication

An API token of a manager is required for authorization. To get an API token via the Operator Control Panel, see Viewing and updating Manager's information. 

The manager's API token specified in an API request determines:

• The role and access level of the manager, which determine the availability of a method.
• The current reseller and downstream resellers accessible within a method.

Specify your API token in the X-Api-Token header.

Parameter types

The following types of parameters can be sent in an API request:

• Path — a part of a request URL. For example, /items/{item_id} where {item_id} is a path parameter value.
• Query — an additional parameter of a request URL after ?. For example, /items?id={item_id} where id is a query parameter key and {item_id} is a query parameter value. Several query parameters should be specified using &. For example, /items?page[size]={page_size}&page[number]={page_number}.
• Form — a JSON body of PUT, POST, and PATCH requests for adding or updating data.
• Header — a header parameter of requests. For example, API v3 supports token-based authorization using the X-Api-Token header.

Language

The API v3 methods use English for error messages by default, similar to using the header X-Api-Locale: en. Some methods also support Russian. To switch to Russian in error messages, use the header X-Api-Locale: ru.

HTTP status codes

Responses can include one of the standard HTTP status codes, in addition to describing data. HTTP response status codes indicate whether a request has been completed successfully. See the list of HTTP status codes.

Error responses

If a request is completed with an error, the method responds with the corresponding HTTP status code and the error description. Some API v3 methods support the following unified error response model.