Documentazione API
Esplora l'API completa di Balla Stats con la documentazione interattiva di Swagger. Testa gli endpoint, visualizza gli schemi ed esegui l'autenticazione direttamente nel browser.
Prerequisiti
Prima di esplorare la documentazione dell'API, è necessario:
- Un account Balla Stats
- Conoscenza di base delle API REST
Esplora l'API completa di Balla Stats con la documentazione interattiva di Swagger. Testa gli endpoint, visualizza gli schemi ed esegui l'autenticazione direttamente nel browser.
Prova gli endpoint
Esegui chiamate API in tempo reale
Visualizza schemi
Tipi compatibili con TypeScript
Autenticazione
Supporto JWT e chiave API
- Accedi alla documentazione API
- Autenticarsi in Swagger
- Esplora gli endpoint
- Prova una chiamata API
- Comprendere gli schemi di risposta
- Modelli API comuni
Passare a /api-docs nel browser o fare clic su API Docs nella barra laterale. L'interfaccia utente di Swagger carica il riferimento API completo con tutti gli endpoint disponibili.
Fai clic sul pulsante "Autorizza" nella parte superiore della pagina. Inserisci il tuo token al portatore: un JWT dal login o una chiave API. Ciò autentica tutte le richieste successive effettuate tramite l'interfaccia utente di Swagger.
Gli endpoint sono organizzati per categoria per una facile navigazione. Espandi qualsiasi sezione per vedere le operazioni disponibili:
Fare clic su "Provalo" su qualsiasi endpoint per renderlo interattivo. Compila i parametri richiesti, quindi fai clic su "Esegui". Il corpo della risposta, le intestazioni e il codice di stato vengono visualizzati di seguito.
Espandi la sezione Schema sotto qualsiasi endpoint per visualizzare la struttura completa della risposta. Questi tipi sono compatibili con le definizioni TypeScript nel pacchetto @balla-stats/types, rendendo semplice la creazione di integrazioni indipendenti dai tipi.
Caratteristiche dello schema
- Tipi di campo: Stringa, numero, booleano, array, oggetto con definizioni di tipo esatte
- Campi obbligatori: Chiaramente contrassegnati per distinguere le proprietà facoltative da quelle obbligatorie
- Enums: Valori esatti consentiti per campi di stato, ruoli e tipi
- Oggetti nidificati: Espandibile per mostrare la struttura completa delle relazioni
L'API Balla Stats segue modelli coerenti su tutti gli endpoint:
Impaginazione
Utilizza i parametri di query page e limit. Le risposte includono il conteggio totale e i metadati della pagina corrente.
Filtraggio
Filtra i risultati con parametri di query come status, teamId, seasonId e intervalli di date.
Risposte agli errori
Formato coerente con i campi message e statusCode. Gli errori di convalida includono dettagli a livello di campo.
Formati della data
Tutte le date utilizzano il formato ISO 8601 (ad esempio, 2026-02-16T10:30:00.000Z). I timestamp sono sempre in UTC.
Testare prima della codifica
Utilizza Swagger per eseguire test prima di scrivere il codice di integrazione. Verifica che gli endpoint restituiscano i dati previsti.
Seleziona tutti i campi
Controlla gli schemi di risposta per tutti i campi disponibili. Le risposte spesso includono più dati di quanto potresti aspettarti.
Si applicano limiti di velocità
I limiti tariffari si applicano anche alle richieste Swagger. Utilizza le chiavi API per limiti più elevati durante i test estesi.
401 Errore in Swagger
- Fai clic sul pulsante Autorizza e inserisci prima il token
- Assicurati di includere il token completo senza spazi aggiuntivi
- I token JWT scadono: accedi nuovamente se la sessione è scaduta
Risposte vuote
- Controlla che i parametri della query siano corretti (ad esempio, ID gruppo valido)
- Verifica di avere accesso alla risorsa richiesta
- Assicurati che la risorsa esista: prova prima a elencare tutti gli elementi