Перейти к содержимому

Документация Corta

Доступ к системе Corta

Система Corta разделяет бизнес-логику (back-end) и пользовательский интерфейс (front-end) с помощью API, к которому могут обращаться клиенты (веб-приложения и другие пользовательские приложения).

Corta ориентирована на API, что означает, что все операции можно выполнять через API-эндпоинты.

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

Для аутентификации HTTP-запросов система Corta использует JWT-токены (Bearer токены).

JWT-токены предоставляют доступ к системе, поэтому их следует рассматривать как учетные данные для входа и защищать соответствующим образом.

Получение токенов доступа

Прежде чем получить токен доступа, необходимо создать клиента авторизации и системного пользователя. Вы можете использовать уже существующего пользователя (например, себя) или создать отдельного пользователя.

Убедитесь, что у пользователя есть достаточные роли для доступа к необходимым ресурсам.

Создайте нового клиента авторизации с типом предоставления client_credentials. Укажите ID выбранного пользователя в поле «Имя пользователя для имперсонации» (имперсонация — это указание пользователя, от имени которого выполняются действия).

Если ID пользователя не установлен или указан некорректно, будет возвращена ошибка: "auth client security configuration invalid".

Пример запроса через c URL для получения токена доступа:
curl -X POST $CORTA_URL/auth/oauth2/token \
     -d grant_type=client_credentials \
     -d scope=api \
     -u client id:client secret

Пример с реальными данными:
curl -X POST $CORTA_URL/auth/oauth2/token \
     -d grant_type=client_credentials \
     -d scope=api \
     -u 229978909641277628:sMVVcYpXE6bOUm6gG0sJGKmDOzEgkYyhvKyrmcU9fGY8M4GhLd90lThZDxUUFLC9

Пример ответа:
{
  "access_token": "ey...MsLA",
  "expires_in": 7200,
  "refresh_token_expires_in": 0,
  "scope": "api",
  "sub": "229974909641277121",
  "token_type": "Bearer"
}

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

Использование токенов доступа

Каждый HTTP-запрос к защищённому ресурсу должен включать Bearer JWT-токен в заголовке авторизации.

Пример ошибки при отсутствии авторизации:
{
  "error": {
    "message": "Unauthorized"
  }
}

Пример запроса с авторизацией через cURL:
curl "$CORTA_URL" \
  -H 'accept: application/json, text/plain, */*' \
  -H "authorization: Bearer $JWT";

Пример запроса без авторизации через cURL:
curl "$CORTA_URL" \
  -H 'accept: application/json, text/plain, */*';

Эндпоинты с альтернативной аутентификацией

GET /namespace/{namespaceID}/attachment/{kind}/{attachmentID}/original/{name}

GET /namespace/{namespaceID}/attachment/{kind}/{attachmentID}/preview.{ext}

Эндпоинты

Каждая инстанция Corta включает встроенную справку по API, доступную по эндпоинту /docs.

  • Если API размещается на отдельном поддомене (например, два Docker-контейнера для веб-приложения и API), URL будет выглядеть следующим образом:
    https://api.$BASE_URL/docs.

  • Если API и веб-приложение размещены на одном домене (один Docker-контейнер), URL будет выглядеть следующим образом:
    https://$BASE_URL/api/docs.

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

Системные эндпоинты:

  • HTTP_ENABLE_DEBUG_ROUTE

    /__profiler — данные профилирования сервера в формате для инструмента pprof.

    /__routes — список всех зарегистрированных маршрутов.

    /__eventbus — список всех зарегистрированных триггеров скриптов автоматизации.

    /__corredor — список всех зарегистрированных скриптов автоматизации.

  • HTTP_ENABLE_VERSION_ROUTE

    /version — отображает время сборки и версию Corta.

  • HTTP_ENABLE_HEALTHCHECK_ROUTE

    /healthcheck — выполняет проверку состояния системы и отображает результат.

Формат данных ответа

Система Corta использует три различных формата ответов в зависимости от выполняемой операции и статуса.

Обратите внимание: ошибки возвращаются со статусом 200 OK вместо стандартных кодов 4xx/5xx по историческим причинам. Клиенты API обрабатывают это и корректно интерпретируют ошибки.

Работа с одной записью

При работе с одной записью она возвращается в объекте response.

{
  "response": {...}
}

Работа с несколькими записями

При работе с несколькими записями они возвращаются в массиве setвместе с объектом фильтрации filter.

{
  "response": {
    "filter": {...},
    "set": [...]
  }
}

Структура объекта filter зависит от ресурса. Обычно он содержит данные о применённых фильтрах.

Ошибка

При возникновении ошибки сообщение возвращается в поле error.message.

{
  "error": {
    "message": "..."
  }
}

Если включена трассировка ошибок через переменную окружения HTTP_ERROR_TRACING, дополнительно возвращаются свойства stack и wrap. Это полезно для отладки, но не рекомендуется для использования в рабочем окружении.

{
  "error": {
    "message": "...",
    "stack": [...],
    "wrap": {...}
  }
}

Навигация по документу