Перейти до вмісту
Sursa Developers

Адреса 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. Пам’ятайте, що ключ, який використовується в браузері, бачить користувач цього браузера.