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] то это никаким образом недолжно повлиять на систему.