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

Введение

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

Аудитория

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

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

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

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

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

Методы /api/vendor/v1/ и /api/vendor/v2/ устарели. Рекомендуется использовать соответствующие методы API v3 /api/v3/resellers/ (см. Реселлеры). Если в API v3 нет подходящего метода, рекомендуется использовать полностью совместимые методы /api/v1/reseller/ и /api/v2/reseller/.

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

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

Переменная {base_url} в описании методов — это URL ActivePlatform (например, https://test.activeplatform.com).

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-кодов состояния совместно с телом ответа. Код ответа показывает, был ли успешно выполнен запрос. Подробнее см. Список кодов.

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

Возможные типы передаваемых параметров в 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).

Выбор языка

По умолчанию сообщения об ошибках API v3 возвращаются на английском языке, что эквивалентно использованию значение заголовка X-Api-Locale: en. Некоторые методы API v3 поддерживают как английский, так и русский язык в сообщениях об ошибках. Для выбора русского языка необходимо указать значение заголовка X-Api-Locale: ru.

Ответы в случае ошибки

В случае ошибки выполнения запроса метод возвращает ответ с кодом статуса ошибки и текстом сообщения об ошибке. Некоторые методы API v3 поддерживают единую модель ответа для случаев, когда выполнение запроса завершилось ошибкой.