Passare all’indirizzo dell’API

Le integrazioni precedenti chiamano l’API sull’indirizzo principale di Sursa, quello che le persone aprono nel browser, per esempio https://app.sursa.com/v1/…. Ora l’API ha anche un indirizzo proprio, https://api.sursa.com nel cloud o https://api.<your domain> nella tua installazione. È pensato per le integrazioni: scala orizzontalmente dietro un bilanciatore di carico e serve soltanto l’API.

Non sei obbligato a spostarti. L’indirizzo principale continua a servire /v1 per le integrazioni esistenti, senza data di fine e senza reindirizzamenti. Spostati quando ti conviene, per avere i vantaggi dell’indirizzo dell’API, e usalo per ogni nuova integrazione.

Cosa resta uguale

Percorsi, parametri, campi, codici di errore ed eventi: GET /v1/cards è la stessa richiesta su entrambi gli indirizzi.
Le chiavi API. Le stesse chiavi kb_ e kbsrc_ funzionano su entrambi gli indirizzi, con lo stesso ruolo, gli stessi ambiti e lo stesso profilo dati.
Chiavi di idempotenza, limiti di frequenza e quote. Le richieste su entrambi gli indirizzi contano per le stesse quote dell’organizzazione.
I webhook. Consegne, firme e segreti non dipendono dall’indirizzo che chiami.
I link nelle risposte. doc_url di un errore punta a questo portale e l’intestazione Link di una pagina di un elenco punta all’indirizzo dell’API, qualunque sia l’indirizzo che chiami.

Cosa cambia sull’indirizzo dell’API

Sull’indirizzo principale	Sull’indirizzo dell’API
Ogni endpoint dell’applicazione web, compresi quelli interni	Solo gli endpoint del riferimento API pubblico. Qualsiasi altro percorso risponde `404` con il codice `api.not_found`.
Una chiave in `X-API-Key` o `Authorization`, oppure un cookie di sessione del browser	Una chiave o un token di accesso OAuth, preferibilmente in `Authorization: Bearer`. I cookie vengono ignorati.
`GET /auth/me`	`GET /v1/me`. I percorsi sotto `/auth/` non vengono serviti.
La modalità “View as” (vedere la base come la vede un profilo dati) tramite cookie	L’intestazione `X-View-As`, per le chiavi con il ruolo `admin`.
Un solo server, o un insieme fisso	Più server dietro un bilanciatore di carico.

L’ultima riga conta in un solo caso: una risposta in streaming di POST /v1/chat. Uno stream interrotto riprende da Last-Event-ID solo sul server che scrive la risposta. Se la tua integrazione riprende gli stream, assegna a ogni domanda un request_id, così un nuovo tentativo su un altro server riceve la risposta salvata invece di una seconda risposta. Vedi Riprendere uno stream interrotto.

Prima di spostarti

Verifica che ogni chiamata sia pubblica. Elenca i percorsi che la tua integrazione chiama e cerca ciascuno nel riferimento API, oppure confrontali con la specifica del nuovo indirizzo:

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 percorso che manca nel riferimento pubblico appartiene all’applicazione web. Funziona ancora sull’indirizzo principale, ma non viene servito sull’indirizzo dell’API, e la sua forma non è un impegno pubblico. Sostituiscilo con un endpoint pubblico, oppure mantieni quella parte dell’integrazione sull’indirizzo principale e comunica al tuo referente in Sursa di cosa hai bisogno.

Verifica come ti autentichi. Se l’integrazione accede con la password di un utente e un cookie di sessione, spostala prima su una chiave API. Se invia X-API-Key, passare a Authorization: Bearer è consigliato ma non obbligatorio.

Verifica la tua rete. Consenti nel firewall e nei proxy l’HTTPS in uscita verso il nuovo nome host.

Spostarsi passo dopo passo

Rendi l’URL di base un’impostazione della tua integrazione, se non lo è già.

Prova il nuovo indirizzo con una richiesta di lettura:

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

Esegui la suite di test della tua integrazione sul nuovo indirizzo, con una chiave di test e una raccolta di test.
Sposta una parte del traffico, per esempio un worker o un ambiente, e cerca nei log 404 api.not_found, 401 e 5xx. Ogni risposta porta X-Request-Id; conservalo insieme ai log.
Sposta il resto. Mantieni per un po’ il vecchio URL di base nella configurazione, così puoi tornare indietro in pochi secondi.

Cosa verificare dopo lo spostamento

GET /v1/health sul nuovo indirizzo restituisce la stessa version del vecchio.
Le intestazioni RateLimit sono presenti nelle risposte. Se la tua integrazione si autoregola in base a X-RateLimit-*, può continuare a farlo: vengono inviati entrambi gli insiemi. Vedi Limiti di frequenza e quote.
Se la tua integrazione funziona in un browser, non ha più bisogno di un tuo proxy per CORS: l’indirizzo dell’API consente richieste da qualsiasi origine, senza cookie.