Skip to main content
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 di esempio - 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:
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.

​
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/{taxId}/financials.
  • Una modifica non retrocompatibile viene rilasciata come un nuovo endpoint con suffisso -vN (ad esempio /companies/{taxId}/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.