👨‍💻Разработчикам

Введение

API CosmoConnect позволяет вам управлять ресурсами в облаке программным способом с использованием обычных HTTP-запросов.

Множество функций, которые доступны в CosmoConnect, также доступны через API, что позволяет вам автоматизировать ваши собственные сценарии.

В этой документации сперва будет описан общий дизайн и принципы работы API, а после этого конкретные конечные точки. Также будут приведены примеры запросов к ним.

Запросы

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

Метод	Применение
GET	Извлекает данные о коллекциях и отдельных ресурсах.
POST	Для коллекций создает новый ресурс этого типа. Также используется для выполнения действий с конкретным ресурсом.
PUT	Обновляет существующий ресурс.
PATCH	Некоторые ресурсы поддерживают частичное обновление, то есть обновление только части атрибутов ресурса, в этом случае вместо метода PUT будет использован PATCH.
DELETE	Удаляет ресурс.

Методы POST, PUT и PATCH могут включать объект в тело запроса с типом содержимого application/json.

Параметры в запросах

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

• limit — обозначает количество записей, которое необходимо вернуть

• offset — указывает на смещение, относительно начала списка

• search — позволяет указать набор символов для поиска

• sort — можно задать правило сортировки коллекции

Ответы

Запросы вернут один из следующих кодов состояния ответа HTTP:

Статус	Описание
200 OK	Действие с ресурсом было выполнено успешно.
201 Created	Ресурс был успешно создан. При этом ресурс может быть как уже готовым к использованию, так и находиться в процессе запуска.
204 No Content	Действие с ресурсом было выполнено успешно, и ответ не содержит дополнительной информации в теле.
400 Bad Request	Был отправлен неверный запрос, например, в нем отсутствуют обязательные параметры и т. д. Тело ответа будет содержать дополнительную информацию об ошибке.
401 Unauthorized	Ошибка аутентификации.
403 Forbidden	Аутентификация прошла успешно, но недостаточно прав для выполнения действия.
404 Not Found	Запрашиваемый ресурс не найден.
409 Conflict	Запрос конфликтует с текущим состоянием.
423 Locked	Ресурс из запроса заблокирован от применения к нему указанного метода.
429 Too Many Requests	Был достигнут лимит по количеству запросов в единицу времени.
500 Internal Server Error	При выполнении запроса произошла какая-то внутренняя ошибка. Чтобы решить эту проблему, лучше всего создать тикет в панели управления.

Ограничение скорости запросов (Rate Limiting)

Чтобы обеспечить стабильность для всех пользователей, CosmoConnect защищает API от всплесков входящего трафика, анализируя количество запросов c каждого аккаунта к каждой конечной точке.

Если ваше приложение отправляет более 20 запросов в секунду на одну конечную точку, то для этого запроса API может вернуть код состояния HTTP 429 Too Many Requests.

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

Доступ к API осуществляется с помощью JWT-токена. Токенами можно управлять внутри панели управления CosmoConnect в разделе API.

Токен необходимо передавать в заголовке каждого запроса в формате:

Authorization: Bearer $COSMO_TOKEN

Чтобы использовать приведенные примеры, не подставляя каждый раз в них свой токен, вы можете добавить токен один раз в переменные окружения в вашей консоли. Например, на Linux это можно сделать с помощью команды:

COSMO_TOKEN="token"

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

Обратите внимание, что все значения в этой документации являются примерами. Не полагайтесь на идентификаторы операционных систем, тарифов и т.д., используемые в примерах. Используйте соответствующую конечную точку для получения значений перед созданием ресурсов.

Версионирование

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

Мажорная версия каждой конечной точки обозначается в пути запроса, например, запрос /api/v1/user указывает, что этот метод имеет версию 1.

Отправка запросов

Отправляйте запросы на api.cosmoconnect.ru, с указанием мажорной версии конечной точки запроса.

Пример: https://api.cosmoconnect.ru/v1/user/auth

Авторизация и получение токена

POST /v1/user/auth

Получение API токена с помощью логина и пароля от аккаунта.

Headers

Name	Value
Content-Type	application/json

Body

Name	Type	Description
username	string	Имя пользователя
password	string	Пароль

Response

200

{
    "status": "Authorized",
    "token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJpZCI6MCwiZW1haWwiOiJ0ZXN0IiwiaWF0IjoxNzEwNjY0MTU5LCJleHAiOjE3MTE5NjAxNTl9.mc48ZZhx7z2OvYX-DehnDOwCf6ayKX0hoc3NtquPU-o"
}

401

{
  "status": "Error",
  "msg": "Wrong creditnals"
}