Passar a l’adreça de l’API

Les integracions anteriors criden l’API a l’adreça principal de Sursa, la que la gent obre al navegador, per exemple https://app.sursa.com/v1/…. Ara l’API també té la seva pròpia adreça: https://api.sursa.com al núvol o https://api.<your domain> a la vostra instal·lació. Està pensada per a les integracions: s’amplia horitzontalment darrere d’un balancejador de càrrega i no serveix res més que l’API.

No cal que canvieu. L’adreça principal continua servint /v1 per a les integracions existents, sense data de finalització i sense redireccions. Canvieu quan us convingui, per aprofitar els avantatges de l’adreça de l’API, i feu-la servir per a totes les integracions noves.

Què es manté igual

Els camins, els paràmetres, els camps, els codis d’error i els esdeveniments: GET /v1/cards és la mateixa sol·licitud a totes dues adreces.
Les claus d’API. Les mateixes claus kb_ i kbsrc_ funcionen a totes dues adreces, amb el mateix rol, els mateixos àmbits i el mateix perfil de dades.
Les claus d’idempotència, els límits de freqüència i les quotes. Les sol·licituds a totes dues adreces compten per a les mateixes quotes de l’organització.
Els webhooks. Els lliuraments, les signatures i els secrets no depenen de l’adreça que crideu.
Els enllaços de les respostes. El doc_url d’un error apunta a aquest portal, i la capçalera Link d’una pàgina d’una llista apunta a l’adreça de l’API, sigui quina sigui l’adreça que crideu.

Què és diferent a l’adreça de l’API

A l’adreça principal	A l’adreça de l’API
Tots els punts finals de l’aplicació web, inclosos els interns	Només els punts finals de la referència de l’API pública. Qualsevol altre camí respon `404` amb el codi `api.not_found`.
Una clau a `X-API-Key` o `Authorization`, o una galeta de sessió del navegador	Una clau o un token d’accés OAuth, preferiblement a `Authorization: Bearer`. Les galetes s’ignoren.
`GET /auth/me`	`GET /v1/me`. Els camins de `/auth/` no se serveixen.
El mode «View as» (veure la base com la veu un perfil de dades) per galeta	La capçalera `X-View-As`, per a les claus amb el rol `admin`.
Un servidor, o un conjunt fix	Diversos servidors darrere d’un balancejador de càrrega.

L’última fila només importa en un cas: una resposta de POST /v1/chat transmesa en temps real. Un flux interromput continua des de Last-Event-ID només al servidor que escriu la resposta. Si la vostra integració reprèn fluxos, doneu un request_id a cada pregunta, perquè un reintent en un altre servidor rebi la resposta desada en lloc d’una segona resposta. Vegeu Reprendre un flux interromput.

Abans de canviar

Comproveu que totes les crides siguin públiques. Feu una llista dels camins que crida la vostra integració i busqueu-los un per un a la referència de l’API, o compareu-los amb l’especificació de l’adreça nova:

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

Un camí que no apareix a la referència pública pertany a l’aplicació web. Continua funcionant a l’adreça principal, però no se serveix a l’adreça de l’API, i la seva forma no és un compromís públic. Substituïu-lo per un punt final públic, o mantingueu aquesta part de la integració a l’adreça principal i expliqueu a la vostra persona de contacte a Sursa què necessiteu.

Comproveu com us autentiqueu. Si la integració inicia la sessió amb la contrasenya d’un usuari i una galeta de sessió, passeu-la primer a una clau d’API. Si envia X-API-Key, es recomana passar a Authorization: Bearer, però no és obligatori.

Comproveu la xarxa. Permeteu l’HTTPS de sortida cap al nom d’amfitrió nou al vostre tallafoc i als vostres servidors intermediaris.

Canviar pas a pas

Feu que la URL base sigui un paràmetre de configuració de la vostra integració, si encara no ho és.

Proveu l’adreça nova amb una sol·licitud de lectura:

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

Executeu el conjunt de proves de la vostra integració amb l’adreça nova, amb una clau de prova i una col·lecció de prova.
Passeu-hi una part del trànsit, per exemple un procés de treball o un entorn, i vigileu si apareixen 404 api.not_found, 401 i 5xx als vostres registres. Cada resposta porta X-Request-Id; deseu-lo amb els vostres registres.
Passeu-hi la resta. Mantingueu durant un temps la URL base anterior a la configuració per poder tornar enrere en pocs segons.

Què cal comprovar després del canvi

GET /v1/health a l’adreça nova retorna la mateixa version que a l’antiga.
Les respostes porten les capçaleres RateLimit. Si la vostra integració es frena a si mateixa segons X-RateLimit-*, ho pot continuar fent: s’envien tots dos conjunts. Vegeu Límits de freqüència i quotes.
Si la vostra integració s’executa en un navegador, ja no necessita un servidor intermediari propi per a CORS: l’adreça de l’API permet sol·licituds des de qualsevol origen, sense galetes.