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

Formatting

Conventions

Example

Bold

For API method name, commands, etc.

The Update an Account method allows to update an account information.

Italic

Used to refer to words used as a term.

A User is a person who uses the Customer Control Panel to access the Services.

Courier

Used to identify API methods, configuration files, etc.

To create an account use method 

POST/api/vendor/v1/accounts.json

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 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 id parameter.
  • Form — a 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.