Перейдіть на адресу API

Старіші інтеграції викликають API на основній адресі Sursa, тій, яку люди відкривають у браузері, наприклад https://app.sursa.com/v1/…. Тепер API має й власну адресу: https://api.sursa.com у хмарі або https://api.<your domain> у вашій інсталяції. Вона створена для інтеграцій: масштабується горизонтально за балансувальником навантаження й обслуговує тільки API.

Переходити не обов’язково. Основна адреса й далі обслуговує /v1 для наявних інтеграцій — без кінцевої дати й без перенаправлення. Переходьте, коли вам зручно, щоб отримати переваги адреси API, і використовуйте її для кожної нової інтеграції.

Що лишається без змін

Шляхи, параметри, поля, коди помилок і події: GET /v1/cards — той самий запит на обох адресах.
Ключі API. Ті самі ключі kb_ і kbsrc_ працюють на обох адресах з тими самими роллю, областями доступу й профілем доступу.
Ключі ідемпотентності, ліміти частоти та квоти. Запити на обидві адреси зараховуються до тих самих квот організації.
Вебхуки. Доставки, підписи й секрети не залежать від адреси, яку ви викликаєте.
Посилання у відповідях. doc_url помилки веде на цей портал, а заголовок Link сторінки списку — на адресу API, хоч би яку адресу ви викликали.

Що відрізняється на адресі API

На основній адресі	На адресі API
Усі операції вебзастосунку, зокрема внутрішні	Лише операції публічного довідника API. Будь-який інший шлях відповідає `404` з кодом `api.not_found`.
Ключ у `X-API-Key` або `Authorization` чи cookie сесії браузера	Ключ або токен доступу OAuth, бажано в `Authorization: Bearer`. Cookie ігноруються.
`GET /auth/me`	`GET /v1/me`. Шляхи в `/auth/` не обслуговуються.
Режим «View as» (перегляд від імені вибраної ролі та профілю доступу) через cookie	Заголовок `X-View-As` для ключів із роллю `admin`.
Один сервер або фіксований набір серверів	Кілька серверів за балансувальником навантаження.

Останній рядок важливий лише в одному випадку: для потокової відповіді POST /v1/chat. Обірваний потік продовжується з Last-Event-ID лише на тому сервері, що пише відповідь. Якщо ваша інтеграція відновлює потоки, задавайте кожному запитанню request_id, щоб повтор на іншому сервері отримав збережену відповідь, а не другу. Див. Відновіть обірваний потік.

Перед переходом

Перевірте, що кожен виклик публічний. Складіть список шляхів, які викликає ваша інтеграція, і знайдіть кожен у довіднику API або порівняйте їх зі специфікацією нової адреси:

curl -s https://api.sursa.com/openapi.json \
  | jq -r '.paths | to_entries[] | .key as $p | .value | keys[] | ascii_upcase + " " + $p' \
  | sort > public-operations.txt

Шлях, якого немає в публічному довіднику, належить вебзастосунку. Він і далі працює на основній адресі, але на адресі API не обслуговується, а його форма не є публічним зобов’язанням. Замініть його публічною операцією або залиште цю частину інтеграції на основній адресі й розкажіть своєму контакту в Sursa, що вам потрібно.

Перевірте спосіб автентифікації. Якщо інтеграція входить із паролем користувача та cookie сесії, спершу переведіть її на ключ API. Якщо вона надсилає X-API-Key, перейти на Authorization: Bearer рекомендовано, але не обов’язково.

Перевірте мережу. Дозвольте у своєму брандмауері та проксі вихідний HTTPS до нового імені хоста.

Перехід крок за кроком

Винесіть базову URL-адресу в налаштування своєї інтеграції, якщо вона ще не там.

Спробуйте нову адресу запитом на читання:

curl https://api.example.com/v1/me -H "Authorization: Bearer $SURSA_API_KEY"

Запустіть набір тестів своєї інтеграції на новій адресі з тестовим ключем і тестовою колекцією.
Перемкніть частину трафіку, наприклад один обробник або одне середовище, і стежте в журналах за 404 api.not_found, 401 і 5xx. Кожна відповідь містить X-Request-Id; зберігайте його разом із журналами.
Перемкніть решту. Деякий час тримайте стару базову URL-адресу в конфігурації, щоб за лічені секунди повернутися назад.

Що перевірити після переходу

GET /v1/health на новій адресі повертає ту саму version, що й на старій.
У відповідях є заголовки RateLimit. Якщо ваша інтеграція сама сповільнюється за X-RateLimit-*, вона може робити це й далі: надсилаються обидва набори. Див. Ліміти частоти та квоти.
Якщо ваша інтеграція працює в браузері, їй більше не потрібен власний проксі для CORS: адреса API дозволяє запити з будь-якого походження без cookie.