Quali Rischi Sono Associati alla Definizione dell’API?

Definizione dell’API: di cosa si tratta

La definizione dell’API è l’insieme di documenti e specifiche tecniche che descrivono il funzionamento di un’interfaccia di programmazione delle applicazioni. Include tipicamente endpoint, formati di richiesta/risposta, autenticazione, limiti di frequenza, gestione degli errori, campi dati e regole di versioning.

Nella pratica, la “definizione” non riguarda solo la sintassi. Codifica anche assunzioni come il significato di un campo, la rappresentazione dei timestamp, le coppie di valute o gli strumenti supportati e il comportamento del sistema sotto stress (ad esempio timeout, tentativi di ritrasmissione e guasti parziali). Quando questi dettagli sono errati, incompleti o interpretati diversamente, i risultati dell’implementazione possono discostarsi dall’intento originale.

Rischi legati al funzionamento della definizione dell’API

Rischi operativi e di integrazione

Un rischio principale è che il comportamento implementato dipenda da dettagli contenuti nella definizione dell’API, i quali possono essere fragili. I guasti più comuni includono:

• Deriva di versione: Se il fornitore modifica la versione dell’API o depreca dei campi, un client che si basa sul vecchio contratto può generare richieste errate o interpretare male le risposte.
• Divergenza nella semantica degli errori: Risposte “riuscite” possono comunque contenere dati mancanti o incoerenti. Se la definizione non chiarisce cosa costituisca un risultato accettabile, il client potrebbe procedere con assunzioni non valide.
• Comportamento in termini di latenza e timeout: Anche senza presupporre dati di mercato in tempo reale, ritardi di rete e timeout influiscono su come il client interpreta la definizione. I tentativi di ritrasmissione possono generare azioni duplicate se le regole di idempotenza non sono chiare.

Scenario realistico: un sistema automatizzato analizza una risposta in base ai nomi dei campi documentati. Se la definizione è ambigua riguardo ai campi opzionali, l’analizzatore potrebbe trattare valori assenti come valori predefiniti validi, causando errori successivi.

Rischi legati alla controparte e all’ambiente

La definizione dell’API è redatta da un fornitore (o negoziata tra le parti). I sistemi, le politiche e i controlli operativi del fornitore fanno parte dell’ambiente. I rischi includono:

• Comportamento diverso dalla documentazione: Le definizioni possono descrivere il comportamento previsto, ma i sistemi reali possono fallire diversamente sotto carico, durante finestre di manutenzione o quando i componenti interni si degradano.
• Cambiamenti nel controllo di accesso e nell’autenticazione: Se la definizione presuppone un certo flusso di autenticazione, qualsiasi modifica alle regole dei token o ai permessi può bloccare le richieste o alterare i dati restituiti.
• Differenze nell’applicazione dei limiti di frequenza: Le definizioni spesso descrivono i limiti di frequenza, ma l’applicazione pratica può variare (ad esempio, gestione dei picchi). Questo può portare a limitazioni e guasti a catena nell’automazione.

Variabilità di mercato e di esecuzione (anche quando la definizione è stabile)

Per i flussi di lavoro legati al forex, la definizione dell’API potrebbe specificare come vengono rappresentati gli ordini e come vengono inviati i report di esecuzione. Tuttavia, i risultati dipendono da condizioni esterne al contratto API. Limitazioni da considerare:

• Le relazioni storiche non garantiscono risultati futuri. Anche se la definizione è corretta, il mercato può muoversi in modi che alterano lo slippage, la qualità del riempimento o i tempi.
• Differenze nei costi e nel percorso di esecuzione: La definizione potrebbe non catturare completamente tutti i componenti di costo o i vincoli di esecuzione. Ad esempio, la stessa richiesta può subire percorsi diversi o riempimenti parziali.

Assunzione per un esempio semplice: se una definizione API indica un campo chiamato “timestamp”, si deve presumere di conoscerne il fuso orario e la precisione. Se quell’assunzione è errata, qualsiasi calcolo basato sull’ordine degli eventi può fallire anche quando il mercato si comporta normalmente.

Rischi di interpretazione causati da definizioni ambigue o incomplete

Una definizione può essere tecnicamente corretta ma comunque rischiosa da interpretare. I problemi tipici di interpretazione includono:

• Ambiguità di unità: I campi potrebbero essere documentati senza unità chiare (millisecondi contro secondi, valuta base contro valuta quotata, quantità decimali contro intere).
• Lacune di significato: Una risposta potrebbe includere un valore numerico, ma la definizione potrebbe non chiarire cosa rappresenta quel valore (ad esempio, “prezzo” contro “prezzo di riferimento” contro “prezzo eseguito”).
• Invarianti assunti: I client spesso presumono che i campi siano sempre presenti o che i valori rimangano entro certi intervalli. Se la definizione ammette casi limite, il client deve gestirli.

Limitazioni materiali e controlli pratici del rischio

Almeno una limitazione materiale è che i documenti di definizione dell’API descrivono contratti, non risultati garantiti. Indicano cosa inviare e come interpretare gli output, ma non assicurano che i sistemi successivi si comporteranno identicamente in ogni situazione.

Per verificare in modo indipendente i fatti rilevanti, utilizzare un approccio orientato al controllo:

• Leggere la definizione per i casi limite (campi opzionali, codici di errore, ritrasmissioni e regole di versioning).