Введение

Сервис предлагает RESTful API для управления данными в базе данных. API имеет предсказуемые URL-адреса, ориентированные на модели, полагается на стандартные коды HTTP состояния и использует JSON для ввода и вывода данных.

• Принцип API
• Аутентификация
• Коды ошибок

Принцип API

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

Каждый ответ от сервера состоит из определенной схемы, где ключевым полем с главной информацией является data если запрос завершился удачно.

Если запрос завершился неудачно, JSON будет содержать поле errors с массивом ошибок, при этом код HTTP ответа будет соответствовать коду ошибке.

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

например, успешный ответ на запрос: GET /items/action_types?limit=1

{
  "data": [
    {
      "id": "77FA0D45-7D1C-41F4-B152-0998F26697B8",
      "date_created": "2021-10-19T08:58:31.983Z",
      "date_updated": null,
      "name": "Ввести одометр",
      "account": null,
      "begin": null,
      "end": null,
      "description": null,
      "is_deleted": false
    }
  ]
}

Важно

В документации будут использоваться относительные пути в маршрутах API. Что бы узнать ваш базовый адрес, необходимо обратиться к ответственному лицу в нашей организации.

Аутентификация

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

Коды ошибок

Код ошибки	HTTP статус	Описание
FAILED_VALIDATION	400	Неудачная валидация элемента
FORBIDDEN	403	Вам не разрешено выполнять данное действие
INVALID_CREDENTIALS	401	Логин/пароль или токен доступа некорректные
INVALID_IP	401	Ваш IP адрес не в разрешенном списке для текущего пользователя
INVALID_PAYLOAD	400	Входящие данные некорректны
INVALID_QUERY	400	Входящие параметры запроса не могут быть использованы
REQUESTS_EXCEEDED	429	Достигнут предел запросов согласно настроенному лимиту
ROUTE_NOT_FOUND	404	Маршрута не существует
SERVICE_UNAVAILABLE	503	Не удалось использовать внешнюю службу
UNPROCESSABLE_ENTITY	422	Вы пытаетесь сделать что-то нелегальное

Пример ошибки:

{
    "errors": [
        {
            "message": "You don't have permission to access this.",
            "extensions": {
                "code": "FORBIDDEN"
            }
        }
    ]
}