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: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
Aggiungilanguage=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: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 comedeprecatednella specifica. - Non esiste un prefisso globale
/v1- ogni endpoint evolve in modo indipendente, e ogni versione è un’operazione distinta con il proprio schema.