Overstappen naar het API-adres

Eerdere integraties roepen de API aan op het hoofdadres van Sursa, het adres dat mensen in de browser openen, bijvoorbeeld https://app.sursa.com/v1/…. De API heeft nu ook een eigen adres: https://api.sursa.com in de cloud of https://api.<your domain> in je installatie. Dat adres is gebouwd voor integraties: het schaalt uit achter een load balancer en levert niets anders dan de API.

Je hoeft niet over te stappen. Het hoofdadres blijft /v1 leveren voor bestaande integraties, zonder einddatum en zonder doorverwijzing. Stap over wanneer het je uitkomt, om de voordelen van het API-adres te krijgen, en gebruik het voor elke nieuwe integratie.

Wat hetzelfde blijft

De paden, parameters, velden, foutcodes en events: GET /v1/cards is op beide adressen hetzelfde request.
API-sleutels. Dezelfde sleutels kb_ en kbsrc_ werken op beide adressen, met dezelfde rol, scopes en hetzelfde dataprofiel.
Idempotentiesleutels, snelheidslimieten en quota. Requests op beide adressen tellen mee voor dezelfde quota van de organisatie.
Webhooks. Leveringen, handtekeningen en geheimen hangen niet af van het adres dat je aanroept.
Links in responses. doc_url van een fout wijst naar dit portaal, en de header Link van een lijstpagina wijst naar het API-adres, welk adres je ook aanroept.

Wat er anders is op het API-adres

Op het hoofdadres	Op het API-adres
Elk endpoint van de webapplicatie, ook interne	Alleen de endpoints van de openbare API-referentie. Elk ander pad antwoordt met `404` en de code `api.not_found`.
Een sleutel in `X-API-Key` of `Authorization`, of een sessiecookie van de browser	Een sleutel of een OAuth-toegangstoken, bij voorkeur in `Authorization: Bearer`. Cookies worden genegeerd.
`GET /auth/me`	`GET /v1/me`. Paden onder `/auth/` worden niet geleverd.
De modus “View as” (bekijken als een andere gebruiker) via een cookie	De header `X-View-As`, voor sleutels met de rol `admin`.
Eén server of een vaste set	Meerdere servers achter een load balancer.

De laatste rij is maar in één geval van belang: een gestreamd antwoord van POST /v1/chat. Een afgebroken stream gaat vanaf Last-Event-ID alleen verder op de server die het antwoord schrijft. Hervat je integratie streams, geef dan elke vraag een request_id, zodat een nieuwe poging op een andere server het opgeslagen antwoord krijgt in plaats van een tweede antwoord. Zie Een afgebroken stream hervatten.

Voordat je overstapt

Controleer of elke aanroep openbaar is. Maak een lijst van de paden die je integratie aanroept en zoek ze op in de API-referentie, of vergelijk ze met de specificatie van het nieuwe adres:

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

Een pad dat in de openbare referentie ontbreekt, hoort bij de webapplicatie. Het werkt nog steeds op het hoofdadres, maar wordt niet geleverd op het API-adres, en de vorm ervan is geen openbare toezegging. Vervang het door een openbaar endpoint, of houd dat deel van de integratie op het hoofdadres en vertel je contactpersoon bij Sursa wat je nodig hebt.

Controleer hoe je authenticeert. Meldt de integratie zich aan met het wachtwoord van een gebruiker en een sessiecookie, zet haar dan eerst over op een API-sleutel. Stuurt ze X-API-Key, dan is overstappen op Authorization: Bearer aanbevolen, maar niet verplicht.

Controleer je netwerk. Sta in je firewall en proxy’s uitgaand HTTPS-verkeer naar de nieuwe hostnaam toe.

Stap voor stap overstappen

Maak van de basis-URL een instelling van je integratie, als dat nog niet zo is.

Probeer het nieuwe adres met een leesrequest:

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

Voer de testsuite van je integratie uit tegen het nieuwe adres, met een testsleutel en een testcollectie.
Zet een deel van het verkeer over, bijvoorbeeld één worker of één omgeving, en let in je logs op 404 api.not_found, 401 en 5xx. Elke response bevat X-Request-Id; bewaar die bij je logs.
Zet de rest over. Houd de oude basis-URL nog een tijd in je configuratie, zodat je binnen enkele seconden kunt terugschakelen.

Controles na de overstap

GET /v1/health op het nieuwe adres geeft dezelfde version terug als op het oude.
De RateLimit-headers staan in de responses. Remt je integratie zichzelf af op basis van X-RateLimit-*, dan kan ze dat blijven doen: beide sets worden meegestuurd. Zie Snelheidslimieten en quota.
Draait je integratie in een browser, dan heeft ze je eigen proxy voor CORS niet meer nodig: het API-adres staat requests vanaf elke origin toe, zonder cookies.