Переход на адрес 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

Последняя строка важна только в одном случае — для потокового ответа 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 на новое имя хоста.

Пошаговый переход

1. Сделайте базовый URL настройкой своей интеграции, если он ещё ею не является.

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

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

3. Прогоните набор тестов своей интеграции на новом адресе с тестовым ключом и тестовой коллекцией.

4. Переключите часть трафика, например один обработчик или одно окружение, и следите в журналах за 404 api.not_found, 401 и 5xx. Каждый ответ несёт X-Request-Id; сохраняйте его в своих журналах.

5. Переключите остальное. Какое-то время держите старый базовый URL в конфигурации, чтобы можно было за секунды переключиться обратно.

Что проверить после перехода

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