Cosa verificare quando si valuta una definizione API?
Definizione API: di cosa si tratta
La definizione API è il contratto documentato che descrive come un client debba chiamare un’API e come risponderà l’API. Include tipicamente gli endpoint, i formati di richiesta/risposta (ad esempio, campi JSON), i tipi di dati, i parametri obbligatori e opzionali, autenticazione e permessi, limiti di frequenza, formati degli errori e eventuali aspettative dichiarate su tempi o ordini.
In un contesto di trading automatizzato, la definizione API è importante perché ogni passaggio successivo — acquisizione dati, logica dei segnali, decisioni di esecuzione e reporting — dipende da ciò che l’API garantisce rispetto a ciò che semplicemente “cerca” di fornire. L’obiettivo principale della valutazione è comprendere quali parti sono meccanismi stabili e quali possono variare in base alle condizioni di mercato, al carico del sistema e alle politiche del fornitore.
Come verificare una definizione API (checklist oggettiva)
- Completezza del contratto (afvinkpunten)
- Gli endpoint e i metodi sono elencati esplicitamente.
- Gli schemi di richiesta e risposta sono definiti, inclusi significati dei campi e tipi di dati.
- Esistono esempi per risposte normali e per ogni tipo di errore documentato.
- Requisiti di autenticazione e autorizzazione sono dichiarati (ad esempio, come vengono fornite le credenziali e quali accessi sono consentiti).
- Dettagli del comportamento (la parte “come funziona”)
- Verifica se l’API definisce ordinamento o coerenza tra le chiamate (ad esempio, se “più recente” è legato a un timestamp).
- Controlla come vengono rappresentati i timestamp (formato, fuso orario e se riflettono il momento dell’evento o del processamento).
- Verifica come funzionano paginazione, filtro e limiti, inclusi dimensioni massime delle pagine e valori predefiniti.
- Condizioni variabili vs. meccanismi stabili
- Separa elementi stabili (schema, regole dei parametri, codici di errore documentati) da elementi variabili (latenza, lacune nei dati, movimento di mercato, limitazione per carico).
- Tratta qualsiasi affermazione su “in tempo reale” o “streaming” come una dichiarazione comportamentale da verificare tramite test o risposte di esempio, non come una promessa fissa.
- Prove e documentazione Cerca artefatti implementativi che ti permettano di validare il contratto:
- Documentazione che include payload di esempio e risposte di errore.
- Politica di versioning che descrive come vengono introdotte le modifiche e per quanto tempo le vecchie versioni rimangono supportate.
- Risorse di test come ambienti sandbox, endpoint simulati o chiamate di esempio registrate.
- Dichiarazioni chiare di limitazioni (bandiere rosse) Identifica lacune in cui la documentazione è assente o ambigua:
- Definizioni mancanti per campi critici.
- Semantica degli errori poco chiara (ad esempio, se un errore è ripetibile).
- Nessuna descrizione di backpressure, comportamento di rate limiting o di ciò che accade durante interruzioni parziali.
Prove o esempi: cosa significa “verifica”
Un esempio pratico di valutazione basata su prove è eseguire chiamate scriptate che coprano:
- Una richiesta “percorso felice” e confermare che i campi della risposta corrispondano allo schema documentato.
- Almeno una condizione limite, come un parametro non valido che dovrebbe generare un errore documentato.
- Un controllo di latenza/tempistica misurando il tempo di andata e ritorno e confrontandolo con eventuali aspettative dichiarate.
Esempio di assunzione (da dichiarare esplicitamente): se misuri il tempo di risposta con l’orologio del tuo sistema, assumi che il tuo orologio sia ragionevolmente sincronizzato. Senza quell’assunzione, i confronti temporali possono essere fuorvianti.
Limitazioni e modalità di errore da considerare
Come minimo, valuta almeno una modalità di errore significativa:
- Lacune nei dati: l’API potrebbe restituire cronologie incomplete, eventi mancanti o aggiornamenti ritardati.
- Problemi di latenza e ordinamento: anche se esistono timestamp, l’ordine delle chiamate potrebbe non corrispondere all’ordine degli eventi.
- Limitazione di frequenza o throttling: richieste eccessive possono causare ritardi o errori strutturati.
- Deriva dello schema: le versioni dell’API potrebbero cambiare campi, tipi o parametri richiesti.
- Errori di autenticazione/permessi: i token potrebbero scadere o gli ambiti di accesso potrebbero variare a seconda dell’ambiente.
Le relazioni storiche non garantiscono risultati futuri. Anche se le risposte di esempio sembrano coerenti, il comportamento futuro può cambiare quando il fornitore aggiorna i servizi o quando cambiano carico del sistema e volatilità di mercato. I risultati variano anche in base ai costi, al metodo di esecuzione e alla giurisdizione, quindi tratta la definizione API come descrizione di un contratto, non come garanzia di prestazioni.
Criteri di verifica e prossime domande
Usa un chiaro “klaarcriterium” (criterio di completamento) prima dell’integrazione:
- Puoi mappare ogni parametro richiesto e ogni campo restituito a un significato documentato.
- Puoi riprodurre risposte di successo ed errori documentati in un ambiente di test.
- Hai documentato assunzioni su tempi, tentativi ripetuti e completezza dei dati.
- Hai un piano per gestire limiti di frequenza, campi sconosciuti e cambiamenti di versione.
Prossime domande da porre durante la valutazione:
- Qual è esattamente il modello di coerenza documentato dall’API per timestamp e ordinamento?
- Quali errori sono ripetibili e quali indicazioni di backoff sono fornite?