Преминаване към адреса на 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` или бисквитка на сесия в браузъра	Ключ или OAuth токен за достъп, за предпочитане в `Authorization: Bearer`. Бисквитките се пренебрегват.
`GET /auth/me`	`GET /v1/me`. Пътищата под `/auth/` не се обслужват.
Режимът „View as“ (преглед като друг потребител) чрез бисквитка	Заглавката `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 от какво имате нужда.

Проверете как се удостоверявате. Ако интеграцията влиза с паролата на потребител и бисквитка на сесия, първо я преместете на 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 разрешава заявки от всеки origin, без бисквитки.