API

API (Интерфейс программирования аппликации) позволяет клиентам интегрировать СУА c собственной системой, запрашивать и отправлять данные о различных объектах системы.

Пользователь выполняет HTTP запрос в систему, предоставив информацию о желаемых действиях. HTTP команды которые обычно используются в API:

  • GET – прочитать ресурс;
  • POST – изменить состояние ресурса.

Запрошенная информация предоставляется в формате JSON с кодировкой UTF-8. Если используется какой либо другой формат, то это будет описано в описании метода.

HTTP коды идентификации определяют состояние запроса – для успешных запросов, возвращается в ответ код статуса 200. Вместе с ответом также поступает запрошенная информация с сервера.  Ответы будут отличатся в зависимости от  используемого API. Ответы API от различных API типов описаны в соответствующих разделах.

Если произошла ошибка во время отправки запроса, система вернёт ответное сообщение с кодом статуса. Часто встречаемые коды статуса ошибок:

  • Код 400 – Плохой запрос – запрос API не был опознан;
  • Код 401 – Не авторизирован – это означает что данные авторизации либо отсутствуют либо не подходят;
  • Код 403 – Запрещено – это означает что у пользователя нет права доступа к запрашиваемому ресурсу или запрашиваемому действию;
  • Код 404 – Не найдено – это означает что запрашиваемый ресурс не был найден;
  • Код 500 – Внутренняя ошибка сервера – свяжитесь с технической поддержкой.

Коды ошибок предоставляют некоторую общую информацию о типе ошибки, таким образом позволяя пользователю понять причину неполадки.

Некоторые API могут иметь дополнительные или выборочные элементы (параметры) в их ответах. Выборочные параметры могут быть пропущены системой по различным причинам (отсутствие данных, плохие данные, таймаут запроса и прочее). Пользователь стоит иметь ввиду что выборочные параметры не всегда будут присутствовать в ответах на запросы.


Ограничения API

У API есть одно единственное ограничение:

  • Не больше чем 1000 запросов в одну минуту.

Данное ограничение действительно для всех API СУА.


Авторизация API

API аутентификация и авторизация необходима для контролирования её использования для различных клиентов и интеграцией с различными системами. Для того чтобы выполнить авторизированный запрос системным API, пользователь выполняющий запрос должен сначала получить API_key (ключ) от лица пользователя системы.

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

Пример выполнения запроса с применением API_key:

Если API_key  устарел, был удалён или просто отключен, то система выдаст следующий ответ:

Конечные точки API, запрашиваемые параметры а также примеры ответов могут быть просмотрены в “Swagger” через данную ссылку: https://api.fm-track.com

Примечание
При использовании API всегда необходимо указывать версию API. Правило действительно для всех видов API.

Внимание!
Из-за постоянных разработок как API так и сомой системы откуда запрашивается информация, пользователи порой могут получить параметры не указанные в описании. Рекомендуется просто напросто игнорировать неизвестные параметры которые не описаны в документации каждого API.


Версии и совместимость

Решение API постоянно обновляется, совершенствуется и каким либо образом модифицируется, поэтому необходимо понимать что означает “Совместимость” и как она влияет на пользователя когда он использует решение API.

Когда для API выходит обновление, происходит одно из двух:

  • API обратно совместима – это означает что изменения обновления никак не повлияют на рабочий процесс API каким либо образом, поэтому новая версия не создается;
  • API больше обратно не совместима – это означает что некоторые компоненты API были изменены и больше не работают как работали прежде. В таком случае создается новая версия

Что подразумевается под “API Обратно совместимо”:

  • Добавлен новый ресурс API;
  • Были добавлены новые выборочные параметры к существующему API;
  • Были добавлены новые свойства к существующему ответу API;
  • Порядок свойств был изменён в существующем ответе API;
  • Изменение длины или формата ID объектов либо других непрозрачных строк. Пользователь может спокойно предполагать что ID объектов генерируемые в системе никогда не превысит длину 255 символов, но при этом пользователь должен иметь возможность справится с ID потенциальной длины до 255 символов. К примеру, пользователь использует MySQL, ID в таком случае должны хранится в колонке VARCHAR(255) COLLATE utf8_bin (Конфигурация COLLATE гарантирует чувствительность к регистру во время поиска или запроса).
  • Добавление новых типов ENUM. – любая система должна спокойно принимать любые неизвестные типы ENUM. Если к примеру, набор типов изменился от [Private, Business] на [Private, Work, Business]  то это никаким образом недолжно повлиять на систему.