APIs and automation
Decimal Differences in an API: How to Investigate Them Without Changing the Contract
A value-tracing example and two documented cases can help locate precision differences without assuming a cause or changing the contract.
What the documented cases show
A visible difference in a decimal value is not enough to conclude that JSON caused it or to identify where it appeared. The available sources describe two specific situations: they are useful precedents for guiding an investigation, but they do not establish a general rule for all APIs.
Esri recorded a discrepancy in precision after the decimal separator between ArcGIS REST API query results presented in HTML and JSON formats. The scope is described in the [Esri record, BUG-000117969](https://support.esri.com/es-es/bug/the-query-results-in-the-rest-api-in-html-and-json-form-bug-000117969). The record supports saying that this difference was observed in that case; it does not let us determine the cause here or extrapolate to other services.
IBM documents how to avoid decimal arithmetic errors in Db2 for z/OS. The available excerpt mentions the possibility of a division error in static SQL statements and the DEC31 rule. Consult the [IBM article on decimal arithmetic errors](https://www.ibm.com/docs/es/db2-for-zos/13.0.0?topic=statement-avoiding-decimal-arithmetic-errors) to verify the context. It is not a general explanation of how decimals are represented in JSON.
Therefore, separate three things during an investigation: the difference observed, the point in the process where you detect it, and the explanation you still need to verify. This distinction prevents a specific symptom from becoming a conclusion about the entire system.
- Esri documents a discrepancy between two response formats in a specific case.
- IBM addresses a specific decimal arithmetic issue in Db2 for z/OS.
- Neither precedent defines a universal numeric format for other APIs.
Example: Trace the same field from start to finish
The following example is a diagnostic template, not a published result or a format recommendation. Suppose you are testing a field called `amount` and record `123.4500` as the input. During one run, you observe `123.4500` in the request, `123.45` at a processing point, and `123.45` in the response. The example shows only how to note a textual difference; it does not let you conclude whether the interpreted value changed, whether rounding occurred, or which component produced the observation.
Trace the real case that concerns you. Note the field name and copy what you observe at each boundary you can access: the data prepared by the API caller, the request actually sent, the data received by the service if you can observe it, any relevant intermediate value, and the response received. If you can access only the request and response, record those two endpoints and make clear that you did not observe the internal stages.
To make the example reproducible, keep the steps that produce it with the sample: which operation was run, with what input, and what response was obtained. If you compare two runs, change only one relevant condition at a time and record which one changed. Do not change the value, operation, and representation simultaneously, or it will be harder to tell what difference you are comparing.
Compare captured samples, not just a screen or report that may present the data differently. If the difference appears only in a view, note that and try to obtain the corresponding request or response as well. Record the first point where you can observe it; that is a practical finding, not automatic proof of the internal cause.
- Field: `amount`. Observed input: `123.4500`.
- Processing: record the value observed, or state that the stage is not visible.
- Output: copy the response received and note whether the difference was already present earlier.
- Label the case as illustrative if you use invented values to prepare a test.
How to prepare a useful check
Before running the test, be specific about what you want to find out. For example: “At what point in this process does the difference between the value I send and the one I receive first appear?” This is more verifiable than “Why does JSON change decimals?”, which assumes a cause that has not yet been demonstrated.
Use a small sample that reproduces the case, and keep the input the same for comparisons. Identify the affected endpoint and operation, and note whether the response came from the same run or a separate test. If the problem appears only with a certain operation, record that condition rather than presenting it as general behavior.
Then compare each observation with the previous one: prepared request versus sent request; sent request versus received response; and, when possible, the input and output data of the stage under investigation. If you cannot access a stage, do not fill it in with an assumption. Write “not observed” and continue with the boundaries you can check.
Repeating the same steps can help document whether you observe the discrepancy again under those conditions. If the result changes, record that too. Neither result identifies a cause on its own: they help describe the case and formulate the next check.
- Define a specific question before running the test.
- Keep the sample fixed and record any condition you change.
- Distinguish observed data, inaccessible stages, and pending hypotheses.
- Save enough steps for someone else to repeat the case.
Interpret findings without changing the contract
A test like this can show that two observations differ and narrow down where the difference is detected. On its own, it does not establish the internal behavior that produced it. Things you might investigate include a difference in the sample sent, in observed processing, or in how the result is presented; treat these as possibilities to verify, not confirmed explanations.
Do not convert the field to a string, change its scale, or round it as a preventive fix without confirming the applicable contract. The available evidence does not support a general recommendation to use numbers, strings, or smaller units, nor does it define a universal scale or rounding rule. A change in representation could change how the field is interpreted under the contract; first find out what the contract allows and what the field means.
If the endpoint documentation does not clarify the representation or expected result, ask the service owner about the reproducible case. Request an answer specific to the field, operation, and endpoint involved. A concrete definition lets you decide what to compare; the absence of a definition does not authorize inferring a rule for other services.
- Treat the first point where you see the difference as an observation boundary, not a confirmed cause.
- Check the contract before changing the type, scale, or rounding.
- Put the unresolved question to the provider specifically and with reproducible details.
Share the case and its limitations
When asking for help, share a minimal sample that demonstrates the difference and the steps needed to reproduce it. State what value you expected, what you observed, and which stages you were able to measure. If a stage was not visible, say so explicitly. This lets the person reviewing the case distinguish the input data, the result, and the questions that remain unanswered.
Before saving or sharing traces, remove credentials and personal or sensitive data that are not needed for diagnosis. Limit who can access the samples and how long they are retained, in line with the needs of the investigation.
Finally, keep your conclusion proportionate to the test: you can report a reproducible difference in a specific integration and describe where you detected it. Do not generalize that result to values, operations, or services you did not test. The Esri and Db2 precedents are useful for consulting documented cases, not for replacing the definition of the expected behavior of your API.
- Include the minimal sample, the steps, and the response observed.
- Separate reproducible results from pending hypotheses.
- Redact sensitive information and restrict access to traces.
Frequently asked questions
Does a decimal difference in the response prove that JSON caused it?
No. Esri documents a precision discrepancy between HTML and JSON results in one ArcGIS REST API case, but that precedent does not establish a universal cause for other APIs.
Should I always send decimals as strings?
There is no evidence here to recommend a general format. Check the endpoint contract to see which representation is accepted and how the field should be interpreted.
What can the tracing example help me conclude?
It lets you record observations at different stages and identify where you first detected a difference. On its own, it does not prove the internal cause.
What information should I send to the provider?
A minimal redacted sample, the steps to reproduce it, the observed difference, and the stages you were able to inspect. Also state what expected behavior you need clarified.
Sources and further reading
Documentation consulted while preparing this article.
- Cómo evitar errores de aritmética decimal - Db2 — IBM
- BUG-000117969 for ArcGIS GIS Server — Esri Support
Explore Apification
Related articles
APIs and automation
Webhooks or Polling for Detecting File Changes: How to Choose
Compare notifications and periodic queries to choose a change-detection strategy that fits your latency, workload, and recovery needs.
APIs and automation
Out-of-Order Webhooks: How to Stop an Old Event from Reverting a File’s State
Receipt time does not prove which change happened first. Learn to review the webhook contract and reconcile file state using verifiable criteria.
APIs and automation
How to Identify Files in an API Without Relying on Names or Paths That May Change
Design references that are less dependent on renames and moves: review the OpenAPI contract, save mappings, and test cases that could break synchronization.