Перейти к содержанию
Sursa для разработчиков

Адрес API и окружения

У Sursa API собственный адрес, отдельный от адреса, по которому люди открывают Sursa в браузере. Все пути начинаются с /v1.

Где работает SursaАдрес APIЭтот портал
Облако Sursahttps://api.sursa.comhttps://developers.sursa.com
Ваша собственная установкаhttps://api.<your domain>, как настроил ваш администратор/developers/ на адресе API
Ваша установка без отдельного адреса APIосновной адрес установки/developers/ на основном адресе

Адрес API обслуживает только API: на нём нет страницы входа, cookie и веб-интерфейса. Каждый запрос проходит аутентификацию по ключу API или токену доступа OAuth. Адрес может обслуживаться несколькими серверами за балансировщиком нагрузки; вашей интеграции не нужно знать, сколько их.

Интеграции, которые вызывают API на основном адресе (например, https://app.sursa.com/v1), продолжают работать. Немногие отличия и пошаговый переход описаны в руководстве Переход на адрес API.

Базовый URL

Собирайте каждый запрос из одного базового URL в своей конфигурации, чтобы один и тот же код работал с любым окружением:

export SURSA_API="https://api.sursa.com"
curl "$SURSA_API/v1/me" -H "Authorization: Bearer $SURSA_API_KEY"

Используйте только HTTPS и не допускайте ключ в журналы отправляемых запросов.

Версия и спецификация

GET /v1/health сообщает, работает ли адрес, и возвращает версию Sursa, которая его обслуживает. Он отвечает без ключа, поэтому его можно использовать в мониторинге:

curl https://api.sursa.com/v1/health
{"ok": true, "version": "v1.4.0"}

Это версия выпуска Sursa, а не API. Версия API — info.version в её спецификации. Спецификация API в формате OpenAPI 3.1 опубликована на том же адресе, без аутентификации:

ПутьСодержимое
GET /openapi.jsonПубличная спецификация с этим адресом в servers.
GET /v1/openapi-public.jsonТа же спецификация. Поддерживает ETag и If-None-Match.

С её помощью можно сгенерировать клиент, импортировать API в инструмент вроде Postman или проверять в CI, что ваша интеграция использует только операции ожидаемой версии. Справочник API этого портала построен по тому же файлу.

Тестирование

Отдельного тестового режима в Sursa нет: каждый запрос с ключом работает с настоящими данными своей организации. Чтобы безопасно разрабатывать и тестировать:

  • Создайте для разработки отдельный ключ с самой узкой ролью и только теми областями, которые нужны для работы.
  • Записывайте в отдельную коллекцию, например sandbox, которую видит только ваша команда, и удалите её, когда закончите.
  • Если у вашей компании есть отдельная организация или установка Sursa для тестов, направьте на неё базовый URL и ключ. Больше в коде ничего не меняется.
  • С самого начала делайте повторы безопасными: передавайте Idempotency-Key с каждым POST и PATCH.

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

Требования к сети

  • Исходящий HTTPS (порт 443) с ваших серверов на адрес API.
  • В правилах межсетевого экрана разрешайте имя хоста, а не фиксированные IP-адреса, если ваша сеть это позволяет: серверы за адресом могут меняться по мере наращивания мощностей.
  • Приложения в браузере могут вызывать API напрямую: ответы разрешают любой источник (Access-Control-Allow-Origin: *) без cookie. Помните, что ключ, используемый в браузере, виден пользователю этого браузера.