API e automazione

Differenze decimali in un’API: come indagarle senza modificare il contratto

Un esempio che segue un valore e due casi documentati aiutano a individuare differenze di precisione senza presumere una causa né modificare il contratto.

Apification
Diagramma che segue un valore decimale dalla richiesta di un’API fino alla risposta

Cosa mostrano i casi documentati

Una differenza visibile in un valore decimale non basta per concludere che sia stata causata da JSON né per sapere in quale punto sia comparsa. Le fonti disponibili descrivono due situazioni specifiche: sono precedenti utili per orientare un’indagine, ma non stabiliscono una regola generale per tutte le API.

Esri ha registrato una discrepanza di precisione dopo il separatore decimale tra i risultati di una query ArcGIS REST API presentati in formato HTML e JSON. L’ambito è descritto nel [registro di Esri, BUG-000117969](https://support.esri.com/es-es/bug/the-query-results-in-the-rest-api-in-html-and-json-form-bug-000117969). Il registro consente di affermare che in quel caso è stata osservata la differenza, ma non di determinarne qui la causa né di estenderla ad altri servizi.

IBM documenta come evitare errori di aritmetica decimale in Db2 for z/OS. Il frammento disponibile menziona la possibilità di un errore di divisione nelle istruzioni SQL statiche e la regola DEC31. Consulta l’[articolo IBM sugli errori di aritmetica decimale](https://www.ibm.com/docs/es/db2-for-zos/13.0.0?topic=statement-avoiding-decimal-arithmetic-errors) per verificarne il contesto. Non è una spiegazione generale della rappresentazione dei decimali in JSON.

Quando indaghi, quindi, distingui tre aspetti: la differenza osservata, il punto del percorso in cui la rilevi e la spiegazione che devi ancora verificare. Questa distinzione evita di trasformare un sintomo concreto in una conclusione sull’intero sistema.

  • Esri documenta una discrepanza tra due formati di risposta in un caso specifico.
  • IBM tratta un problema specifico di aritmetica decimale in Db2 for z/OS.
  • Nessuno di questi precedenti definisce un formato numerico universale per altre API.
Cosa mostrano i casi documentati

Esempio: segui lo stesso campo dall’inizio alla fine

L’esempio seguente è un modello diagnostico, non un risultato pubblicato né una raccomandazione sul formato. Supponi di testare un campo chiamato `importo` e di registrare `123.4500` come input. Durante un’esecuzione osservi `123.4500` nella richiesta, `123.45` in un punto dell’elaborazione e `123.45` nella risposta. L’esempio mostra soltanto come annotare una differenza testuale: non consente di concludere se sia cambiato il valore interpretato, se sia stato effettuato un arrotondamento o quale componente abbia prodotto l’osservazione.

Segui il caso reale che ti interessa. Annota il nome del campo e copia ciò che osservi a ogni confine a cui hai accesso: il dato preparato da chi chiama l’API, la richiesta effettivamente inviata, il dato ricevuto dal servizio se puoi osservarlo, gli eventuali valori intermedi pertinenti e la risposta ricevuta. Se hai accesso solo alla richiesta e alla risposta, registra questi due estremi e specifica che non hai osservato le fasi interne.

Per rendere l’esempio riproducibile, conserva insieme al campione i passaggi che lo producono: quale operazione è stata eseguita, con quale input e quale risposta è stata ottenuta. Se confronti due esecuzioni, modifica una sola condizione pertinente alla volta e annota quale. Non cambiare contemporaneamente il valore, l’operazione e la rappresentazione: altrimenti sarà più difficile capire quale differenza stai confrontando.

Confronta i campioni acquisiti, non soltanto una schermata o un report che potrebbe presentare i dati in modo diverso. Se la differenza compare solo in una visualizzazione, annotalo e cerca di ottenere anche la richiesta o la risposta corrispondente. Registra il primo punto in cui puoi osservarla: è un riscontro pratico, non una prova automatica della causa interna.

  • Campo: `importo`. Input osservato: `123.4500`.
  • Elaborazione: registra il valore osservato oppure indica che questa fase non è visibile.
  • Output: copia la risposta ricevuta e indica se la differenza era già presente prima.
  • Se usi valori inventati per preparare un test, contrassegna il caso come illustrativo.
Esempio: segui lo stesso campo dall’inizio alla fine

Come preparare una verifica utile

Prima di eseguire il test, chiarisci cosa vuoi scoprire. Per esempio: «In quale punto di questo percorso compare per la prima volta la differenza tra il valore che invio e quello che ricevo?». È una domanda più verificabile di «perché JSON modifica i decimali?», che presuppone una causa non ancora dimostrata.

Usa un campione ridotto che riproduca il caso e mantieni invariato lo stesso input durante i confronti. Identifica l’endpoint e l’operazione interessati e annota se la risposta è stata ottenuta nella stessa esecuzione o in un test distinto. Se il problema si presenta solo con una certa operazione, registra questa condizione invece di descriverla come un comportamento generale.

Poi confronta ogni osservazione con quella precedente: richiesta preparata rispetto a richiesta inviata; richiesta inviata rispetto a risposta ricevuta; e, quando possibile, dati in ingresso e in uscita dalla fase esaminata. Se non hai accesso a una fase, non completarla con una supposizione. Scrivi «non osservato» e prosegui con i confini che puoi verificare.

Ripetere gli stessi passaggi può aiutarti a documentare se la discrepanza si ripresenta in quelle condizioni. Se il risultato cambia, annotalo a sua volta. Nessuno dei due esiti individua da solo una causa: servono a descrivere il caso e a formulare la verifica successiva.

  • Definisci una domanda concreta prima di eseguire il test.
  • Mantieni invariato il campione e registra ogni condizione che modifichi.
  • Distingui i dati osservati, le fasi non accessibili e le ipotesi ancora da verificare.
  • Conserva passaggi sufficienti perché un’altra persona possa riprodurre il caso.

Interpreta i riscontri senza modificare il contratto

Un test di questo tipo può mostrare che due osservazioni differiscono e circoscrivere il punto in cui la differenza viene rilevata. Da solo, non stabilisce quale comportamento interno l’abbia prodotta. Potresti indagare, per esempio, una differenza nel campione inviato, in un’elaborazione osservata o nel modo in cui viene presentato il risultato; considerale possibilità da verificare, non spiegazioni confermate.

Non convertire il campo in una stringa, non modificarne la scala e non arrotondarlo come misura preventiva senza aver verificato il contratto applicabile. Le evidenze disponibili non giustificano una raccomandazione generale a favore di numeri, stringhe o unità minori, né definiscono una regola universale di scala o arrotondamento. Un cambiamento di rappresentazione potrebbe modificare il modo in cui il campo viene interpretato in base al contratto; prima verifica cosa ammette e cosa significa.

Se la documentazione dell’endpoint non chiarisce la rappresentazione o il risultato atteso, poni la domanda al responsabile del servizio allegando il caso riproducibile. Chiedi una risposta specifica per il campo, l’operazione e l’endpoint coinvolti. Una definizione concreta permette di decidere cosa confrontare; l’assenza di una definizione non autorizza a dedurre una regola valida per altri servizi.

  • Considera il primo punto in cui vedi la differenza come un confine di osservazione, non come una causa confermata.
  • Consulta il contratto prima di modificare tipo, scala o arrotondamento.
  • Formula la domanda ancora aperta al fornitore in modo specifico e riproducibile.

Condividi il caso e i suoi limiti

Quando chiedi assistenza, condividi un campione minimo che dimostri la differenza e i passaggi necessari a riprodurla. Indica quale valore ti aspettavi, cosa hai osservato e in quali fasi hai potuto effettuare misurazioni. Se una fase non era visibile, dichiaralo esplicitamente. In questo modo chi esamina il caso può distinguere il dato in ingresso, il risultato e le domande ancora senza risposta.

Prima di salvare o condividere le tracce, rimuovi credenziali e dati personali o sensibili non necessari alla diagnosi. Limita chi può accedere ai campioni e per quanto tempo vengono conservati, in base alle esigenze dell’indagine.

Infine, mantieni le conclusioni proporzionate alle prove: puoi segnalare una differenza riproducibile in una specifica integrazione e descrivere dove l’hai rilevata. Non generalizzare questo risultato a valori, operazioni o servizi che non hai testato. I precedenti di Esri e Db2 sono utili per consultare casi documentati, ma non sostituiscono la definizione del comportamento atteso della tua API.

  • Includi il campione minimo, i passaggi e la risposta osservata.
  • Separa i risultati riproducibili dalle ipotesi ancora da verificare.
  • Oscura le informazioni sensibili e limita l’accesso alle tracce.

Domande frequenti

Una differenza decimale nella risposta dimostra che la causa è JSON?

No. Esri documenta una discrepanza di precisione tra risultati HTML e JSON in un caso di ArcGIS REST API, ma questo precedente non stabilisce una causa universale per le altre API.

Devo inviare sempre i decimali come stringhe?

Qui non ci sono elementi sufficienti per raccomandare un formato generale. Verifica nel contratto dell’endpoint quale rappresentazione è ammessa e come deve essere interpretato il campo.

Che cosa permette di concludere l’esempio di tracciamento?

Permette di registrare le osservazioni nelle diverse fasi e di indicare dove hai rilevato per la prima volta una differenza. Da solo non dimostra la causa interna.

Quali informazioni è utile inviare al fornitore?

Un campione minimo con i dati sensibili oscurati, i passaggi per riprodurlo, la differenza osservata e le fasi che hai potuto esaminare. Indica anche quale comportamento atteso vuoi chiarire.

Fonti e approfondimenti

Documentazione consultata per preparare questo articolo.

Scopri Apification

Articoli correlati

Torna al blog