ActivePlatform API Reference Guide

Introduction

The ActivePlatform application programming interfaces (APIs) are defined in 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 easy to use with any programming language.

Audience

This document is intended for research and development engineers who want to integrate ActivePlatform with external services (online store, provisioning services and other external systems).
The reader should be familiar with basic ActivePlatform concepts and ActivePlatform. Operator Control Panel.

Typographical Conventions

API Versions

The following 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/

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 are in JavaScript Object Notation (JSON) format. API responses are encoded with UTF-8.

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

API Token Authentication

Some specific REST API calls, that normally require administrator credentials, can be also authenticated using an API token. The REST API token is linked to a specific user (Operator's employee) and is generated for the instance in the manager's details page of the Operator Control Panel (see Viewing and updating manager's information in the ActivePlatform. Operator Control Panel). 

• API v1 supports token-based authentication using the standard query parameter in the end of the URL, for example, ?api_token={api_token}, where api_token is the API Token.
• API v3 supports token-based authentication using the standard HTTP Authorization header X-Api-Token Header.

HTTP Status Codes

Responses can include one of the following HTTP status codes, in addition to describing data. HTTP response status codes indicate whether a request has been successfully completed. Status codes are not part of endpoint descriptions because the implementation follows the HTTP standard for reporting status. See the list of HTTP status codes.

Parameters types

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

• Path is a parameter as a part of the URL request. The curly braces {} are used to highlight the parameters in the URL request. For example, /items/{itemId}, where the path is the itemId parameter.
• Query — the parameter is added to end of the URL request, for example, /items?id=###, where the query is the id parameter.
• Form — the full description of the parameter type is provided in the following article http://www.w3.org/TR/html401/interact/forms.html#h-17.13.4.

Language

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

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.