Treceți la adresa API

Integrările mai vechi apelează API-ul la adresa principală a Sursa, cea pe care utilizatorii o deschid în browser, de exemplu https://app.sursa.com/v1/…. Acum API-ul are și o adresă proprie, https://api.sursa.com în cloud sau https://api.<your domain> în propria instalare. Ea este construită pentru integrări: se scalează pe mai multe servere în spatele unui echilibrator de sarcină și nu servește nimic altceva decât API-ul.

Nu sunteți obligați să treceți. Adresa principală servește în continuare /v1 pentru integrările existente, fără dată de încheiere și fără redirecționare. Treceți atunci când vă convine, pentru a beneficia de avantajele adresei API, și folosiți-o pentru fiecare integrare nouă.

Ce rămâne la fel

Căile, parametrii, câmpurile, codurile de eroare și evenimentele: GET /v1/cards este aceeași cerere la ambele adrese.
Cheile API. Aceleași chei kb_ și kbsrc_ funcționează la ambele adrese, cu același rol, aceleași domenii de acces și același profil de date.
Cheile de idempotență, limitele de frecvență și cotele. Cererile la ambele adrese se socotesc în aceleași cote ale organizației.
Webhookurile. Livrările, semnăturile și secretele nu depind de adresa pe care o apelați.
Linkurile din răspunsuri. doc_url al unei erori duce la acest portal, iar antetul Link al unei pagini de listă duce la adresa API, indiferent de adresa pe care o apelați.

Ce este diferit la adresa API

La adresa principală	La adresa API
Fiecare endpoint al aplicației web, inclusiv cele interne	Doar endpointurile din referința API publică. Orice altă cale răspunde `404` cu codul `api.not_found`.
O cheie în `X-API-Key` sau `Authorization` ori un cookie de sesiune din browser	O cheie sau un token de acces OAuth, de preferință în `Authorization: Bearer`. Cookie-urile sunt ignorate.
`GET /auth/me`	`GET /v1/me`. Căile din `/auth/` nu sunt servite.
Modul „View as” (vizualizare ca alt utilizator) prin cookie	Antetul `X-View-As`, pentru cheile cu rolul `admin`.
Un singur server sau un set fix	Mai multe servere în spatele unui echilibrator de sarcină.

Ultimul rând contează într-un singur caz: un răspuns transmis în flux de POST /v1/chat. Un flux întrerupt continuă de la Last-Event-ID doar pe serverul care scrie răspunsul. Dacă integrarea reia fluxurile, dați fiecărei întrebări un request_id, astfel încât o reîncercare pe alt server să primească răspunsul salvat în locul unui al doilea răspuns. Vedeți Reluarea unui flux întrerupt.

Înainte de trecere

Verificați că fiecare apel este public. Enumerați căile pe care le apelează integrarea și căutați-le pe fiecare în referința API sau comparați-le cu specificația noii adrese:

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

O cale care lipsește din referința publică aparține aplicației web. Ea funcționează în continuare la adresa principală, dar nu este servită la adresa API, iar forma ei nu este un angajament public. Înlocuiți-o cu un endpoint public sau păstrați acea parte a integrării pe adresa principală și spuneți-i persoanei de contact de la Sursa de ce aveți nevoie.

Verificați cum vă autentificați. Dacă integrarea se autentifică cu parola unui utilizator și un cookie de sesiune, treceți-o mai întâi la o cheie API. Dacă trimite X-API-Key, trecerea la Authorization: Bearer este recomandată, dar nu obligatorie.

Verificați rețeaua. Permiteți HTTPS de ieșire către noul nume de gazdă în firewall și în proxy-uri.

Trecerea pas cu pas

Faceți din URL-ul de bază o setare a integrării, dacă nu este deja.

Încercați noua adresă cu o cerere de citire:

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

Rulați suita de teste a integrării pe noua adresă, cu o cheie de test și o colecție de test.
Mutați o parte a traficului, de exemplu un proces de lucru sau un mediu, și urmăriți în jurnale 404 api.not_found, 401 și 5xx. Fiecare răspuns poartă X-Request-Id; păstrați-l în jurnale.
Mutați restul. Păstrați o vreme vechiul URL de bază în configurație, ca să puteți reveni în câteva secunde.

Ce verificați după trecere

GET /v1/health la noua adresă returnează aceeași version ca la cea veche.
Antetele RateLimit sunt prezente în răspunsuri. Dacă integrarea își reduce singură ritmul după X-RateLimit-*, poate continua să facă asta: se trimit ambele seturi. Vedeți Limite de frecvență și cote.
Dacă integrarea rulează într-un browser, nu mai are nevoie de un proxy propriu pentru CORS: adresa API permite cereri de la orice origine, fără cookie-uri.