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 to use the following standard HTTP methods: GET, PUT, POST and DELETE. Request and response message bodies are in JavaScript Object Notation (JSON) format. API responses are encoded with UTF-8.

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. Status codes are not part of endpoint descriptions because the implementation follows the HTTP standard for reporting status.
See the Hypertext Transfer Protocol — HTTP/1.1, Status Code Definitions standard for the complete list of status codes and their meanings.

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.