ActivePlatform. Руководство по использованию API

Введение

Программные интерфейсы ActivePlatform (API) базируются на архитектуре REST протокола HTTP 1.1 [RFC2616] и предоставляют доступ к ресурсам по путям URI. Каждый запрос работает через протокол передачи гипертекста (HTTP) и позволяет легко взаимодействовать с любым языком программирования.

Аудитория

Документ предназначен для инженеров-разработчиков, которые хотят интегрировать ActivePlatform с внешними сервисами (интернет-магазинами, сервисами предоставления услуг и другими внешними системами).
Читатель должен быть знаком с основными понятиями ActivePlatform, такими как подписка, тарифный план и т.д.

Условные обозначения

Форматирование

Условие

Пример

Bold

Для обозначения названий разделов, подразделов и блоков, названий методов, кнопок, пунктов меню и т.д.

Для создания аккаунта необходимо воспользоваться методом Create an Account.

Italic

Для обозначения ссылок.

Для этого необходимо использовать метод Создание платежа, который описан выше.

Courier
Для описания методов и конфигураций.

Для создания аккаунта необходимо использовать следующий метод

POST/api/vendor/v1/accounts.json

Версионность

Данное руководство содержит описание методов для следующих версий API:

  • API v1 — в пути методов указывается /v1/
  • API v2 — в пути методов указывается /v2/
  • API v3 — в пути методов указывается /v3/

Основные понятия

REST API позволяет использовать такие стандартные методы HTTP запросов как: GET, PUT, POST и DELETE. Формат тела сообщения запроса и ответа - JavaScript Object Notation (JSON). Для тела ответа используется кодировка UTF-8.

API Token аутентификации

Некоторые вызовы REST API, которые обычно требуют учетных данных администратора, могут быть также аутентифицированы с использованием API token. REST API Token привязан к конкретному пользователю (сотруднику Оператора) и может быть получен в Панели Управления Оператора на странице Сотрудника (см. Добавление сотрудника в ActivePlatform. Панель управления Оператора).

API v1 поддерживает аутентификацию по токену с использованием query-параметра в конце URL, например, ?api_token={api_token}, где api_token — полученный API Token.

API v3 поддерживает аутентификацию по токену с использованием заголовка X-Api-Token Header.

Коды состояния HTTP

Ответ может содержать один из следующих HTTP-кодов состояния совместно с телом ответа. Дополнительное текстовое описание статус-кода не следует использовать, так как для ответов используются стандартные описания статус-кодов.
См. Hypertext Transfer Protocol — HTTP/1.1, Status Code Definitions стандарт для получения полного списка кодов состояния и их значения.

Типы параметров

Возможные типы передаваемых параметров в API запросе:

  • Path — параметр используется как часть запроса URL. Для выделения данного типа параметров в URL запросе используются фигурные скобки {}. Например, /items/{itemId}, где path — параметр itemId.
  • Query — параметр добавляется в конце URL, например, /items?id=###, где query параметр - id.
  • Form — параметр используется для описания полезных данных в HTTP запросе при использовании application/x-www-form-urlencoded и/или multipart/form-data в содержимом запроса (подробнее http://www.w3.org/TR/html401/interact/forms.html#h-17.13.4).