Vai al contenuto principale
Poiché l’API Syrto è configurata per cliente, la tua specifica OpenAPI è il riferimento autorevole per la tua API - elenca esattamente gli endpoint, i parametri e la forma delle risposte predisposti per la tua organizzazione. Viene generata per ogni API key e limitata a ciò che quella key può chiamare, quindi è il modo più rapido per vedere cosa espone davvero la tua API.
Vuoi prima vedere com’è fatta una specifica? Consulta il riferimento interattivo per gli endpoint standard - viene reso allo stesso modo della tua specifica.

Visualizzare la tua specifica

La tua specifica è servita come OpenAPI 3.1, in JSON o YAML. Entrambi gli endpoint richiedono la tua API key e non vengono mai addebitati. Crea una key nella dashboard Syrto (solo amministratori), poi scaricala e salvala:
La sandbox serve la stessa specifica su https://sandbox.api.syrto.ai/openapi.json. Poi apri il file salvato in un qualsiasi visualizzatore OpenAPI per sfogliarlo in modo interattivo. Una buona opzione open source è lo Swagger Editor, che rende il file nel tuo browser - la specifica descrive la tua API ma non contiene mai la tua key. Altre opzioni: Scalar (npx @scalar/cli), Postman o un plugin OpenAPI per l’IDE.
Non esiste un visualizzatore della specifica integrato nella pagina, per scelta: la specifica è protetta dalla tua API key segreta. Scaricala con la tua key e visualizzala in uno strumento che controlli tu, anziché incollare la key in una pagina web.

Lingua della specifica

Aggiungi language=it per ottenere la specifica con ogni riepilogo e descrizione in italiano. Il valore predefinito, e language=en, è l’inglese. Struttura, nomi dei campi, enum ed esempi sono identici nelle due lingue, quindi un client generato dall’una o dall’altra è lo stesso.
language funziona sia su /openapi.json sia su /openapi.yaml, e sulla sandbox. Qualsiasi altro valore è un 422 invalid_params. È distinto dal parametro language degli endpoint dati, che localizza nomi ed etichette delle metriche nelle risposte.

Generare un client

La specifica è un contratto indipendente dal linguaggio, quindi puoi generare un client tipizzato dal file salvato con qualsiasi generatore OpenAPI:
Ogni operazione ha un operationId stabile (lo slug dell’endpoint), così i nomi dei metodi generati restano puliti, e il code di errore è un enum tipizzato che copre l’intera tassonomia degli errori - un client generato vede codici esatti, non una stringa generica.

Versionamento

Il versionamento è per risorsa e compare nel nome della risorsa, solo quando una modifica romperebbe i chiamanti esistenti:
  • La prima versione di un endpoint usa il nome pulito della risorsa - ad esempio /companies/{id}/financials.
  • Una modifica non retrocompatibile viene rilasciata come un nuovo endpoint con suffisso -vN (ad esempio /companies/{id}/financials-v2). L’originale continua a funzionare ed è contrassegnato come deprecated nella specifica.
  • Non esiste un prefisso globale /v1 - ogni endpoint evolve in modo indipendente, e ogni versione è un’operazione distinta con il proprio schema.
Questo significa che un’integrazione esistente non si rompe mai in silenzio: una nuova versione principale è un nuovo URL a cui aderisci, e la vecchia continua a servire finché non migri.