Indirizzo dell’API e ambienti

L’API di Sursa ha un indirizzo proprio, separato da quello che le persone usano per aprire Sursa nel browser. Tutti i percorsi iniziano con /v1.

Dove funziona Sursa	Indirizzo dell’API	Questo portale
Cloud di Sursa	`https://api.sursa.com`	`https://developers.sursa.com`
La tua installazione	`https://api.<your domain>`, come configurato dal tuo amministratore	`/developers/` sull’indirizzo dell’API
La tua installazione senza un indirizzo dell’API separato	l’indirizzo principale dell’installazione	`/developers/` sull’indirizzo principale

L’indirizzo dell’API serve solo l’API: non ci sono pagina di accesso, cookie né interfaccia web. Ogni richiesta viene autenticata con una chiave API o con un token di accesso OAuth. L’indirizzo può essere servito da più server dietro un bilanciatore di carico; la tua integrazione non ha bisogno di sapere quanti sono.

Le integrazioni che chiamano l’API sull’indirizzo principale (per esempio https://app.sursa.com/v1) continuano a funzionare. Vedi Passare all’indirizzo dell’API per le poche differenze e un passaggio guidato.

URL di base

Costruisci ogni richiesta a partire da un unico URL di base nella tua configurazione, così lo stesso codice funziona con qualsiasi ambiente:

export SURSA_API="https://api.sursa.com"
curl "$SURSA_API/v1/me" -H "Authorization: Bearer $SURSA_API_KEY"

Usa solo HTTPS e tieni la chiave fuori dai log delle richieste che fai.

Versione e specifica

GET /v1/health indica se l’indirizzo è attivo e restituisce la versione di Sursa che lo serve. Risponde senza chiave, quindi puoi usarla nel monitoraggio:

curl https://api.sursa.com/v1/health

{"ok": true, "version": "v1.4.0"}

Questa è la versione della release di Sursa, non dell’API. La versione dell’API è info.version della sua specifica. La specifica OpenAPI 3.1 dell’API è pubblicata allo stesso indirizzo, senza autenticazione:

Percorso	Contenuto
`GET /openapi.json`	La specifica pubblica, con questo indirizzo in `servers`.
`GET /v1/openapi-public.json`	La stessa specifica. Supporta `ETag` e `If-None-Match`.

Usala per generare un client, per importare l’API in uno strumento come Postman o per verificare nella CI che la tua integrazione usi solo operazioni della versione che ti aspetti. Il riferimento API di questo portale è costruito dallo stesso file.

Test

Sursa non ha una modalità di test separata: ogni richiesta con una chiave opera sui dati reali della sua organizzazione. Per sviluppare e fare test in sicurezza:

Crea una chiave separata per lo sviluppo, con il ruolo e gli ambiti più ristretti che il lavoro richiede.
Scrivi in una raccolta dedicata, per esempio sandbox, che solo il tuo team può vedere, ed eliminala quando hai finito.
Se la tua azienda ha un’organizzazione o un’installazione di Sursa separata per i test, punta lì l’URL di base e la chiave. Nient’altro cambia nel tuo codice.
Rendi sicuri i nuovi tentativi fin dall’inizio: invia una Idempotency-Key con ogni POST e PATCH.

La console Prova in ogni pagina di endpoint del riferimento API invia richieste reali con una chiave che incolli al suo interno. La chiave resta nella memoria della scheda del browser e viene inviata solo all’indirizzo dell’API.

Requisiti di rete

HTTPS in uscita (porta 443) dai tuoi server verso l’indirizzo dell’API.
Nelle regole del firewall consenti il nome host anziché indirizzi IP fissi, dove la tua rete lo permette: i server dietro l’indirizzo possono cambiare quando si aggiunge capacità.
Le applicazioni nel browser possono chiamare l’API direttamente: le risposte consentono qualsiasi origine (Access-Control-Allow-Origin: *) senza cookie. Tieni presente che una chiave usata in un browser è visibile all’utente di quel browser.