An API provider keeps amount numeric but changes its unit from major to minor currency units. Requests still pass and the schema looks valid, yet the consumer stores a different sum. This illustrative case changes the meaning without changing the type. Detecting it before release requires an explicit field definition and an actual business-operation check.
Describe meaning alongside format
A schema defines types and structure. The exchange contract should also explain units, time zones, permitted empty values and field provenance. For money, specify currency and rounding. For a timestamp, identify the event it represents.
OpenAPI provides a standard description of HTTP APIs and a basis for documentation and validation tooling. Business meaning still needs explicit definition and tests. A specification does not prove correct implementation.
Identify actual consumers
Combine documented integrations, access records, call logs and confirmation from accountable teams. No recent traffic does not prove that a consumer is unused: it may run only at period close.
For every consumer, identify an owner, required fields and an acceptance condition. An unknown owner is an unresolved dependency, not silent permission to release.
Test three distinct layers
| Check | What it shows | What it does not prove |
|---|---|---|
| API response | The request received a response | The business record is correct |
| Schema | Format conforms to the contract | Meaning is correct |
| End-to-end scenario | The outcome in the consumer | Every other scenario works |
In this example, follow the original amount through transformation to the stored record. Include zero, fractions, empty values, repeated delivery and an unsupported currency. The process owner agrees expected outcomes; one universal set cannot cover all integrations.
Plan transition and recovery together
Options include a new API version, a separate field or an agreed adapter. Choose based on consumer count and whether updates can happen together. Retain old behaviour with an explicit transition window and an owner for its completion.
Rolling back code may not repair amounts already stored. Define how to locate affected operations, verify them and apply an authorized correction. Reprocessing must not create new business operations.
Prepare the next release
- Describe changes to field format and meaning.
- List consumers and accountable owners.
- Record inputs and expected final records.
- Plan transition, post-release checks and data correction.
Digital Line applies this approach when designing integrations. Verify the actual API, version and configuration of an Intecracy Group product before choosing a connection method.
Questions and answers
Does every change need a new API version?
No. It needs a method that preserves agreed behaviour for existing consumers. Even an added field should be tested against consumer parsing rules.
Is a provider-side test enough?
It is necessary but does not expose every consumer transformation. End-to-end testing should reach the business outcome.
Source
OpenAPI Specification defines the HTTP API description format. The transition method and example above are Digital Line editorial guidance.