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 ActivePlatform Operator (Reseller) Control Panel.

Documentation conventions

Formatting

Conventions

Example

Bold

Names of methods, objects, and values of parameters

Payment model:

  • prepay
  • postpay

Italic

Emphasizing terms

Date and time of the Owner creation

Courier

URLs, parameters, and code examples

POST {base_url}/api/v3/resellers/{reseller_id}

API versions

This guide includes descriptions of methods of the API following versions:

  • API v1 — the method path includes /v1/
  • API v2 — the method path includes /v2/
  • API v3 — the method path includes /v3/

The /api/vendor/v1/ and /api/vendor/v2/ methods are deprecated. It is recommended to use the corresponding API v3 methods /api/v3/resellers/ (see Resellers). If there is no corresponding method in API v3, it is recommended to use the fully compatible /api/v1/reseller/ and /api/v2/reseller/ methods.

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 current reseller and downstream resellers accessible within a method.

  • API v1 and API v2 support token-based authorization using a query parameter ?api_token={api_token}, where {api_token} is a manager's API Token.
  • API v3 supports token-based authorization using 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.

ParameterDescription
errorsList of occurred errors

detailError description in the selected language

sourceInformation about the sources of the error


pointerParameter caused the error

Отзыв | Feedback