Прелазак на адресу 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, без колачића.