Backward-Compatible Blockchain API Schema Changes
Evolve API responses without breaking older clients, including optional fields, unknown enums, nullable values and exact quantity representations.
Overview
When translating these concepts into an integration, keep the scope described by the wallet history api with the result. The examples in wallet transaction history and smart contract event logs show how the same distinction affects neighbouring data questions.
An additive-looking field can still break a strict reader. Compatibility depends on the consumers’ actual parsing rules and on whether existing field meanings remain stable.
Preserve existing semantics
Keep field names, types, units, nullability and defaults stable unless a versioned transition is planned. Adding a required field to requests breaks older callers. Adding a new enum value can break exhaustive switches. Exact integer strings should not become floating-point JSON numbers merely to simplify one client.
Worked example: a new activity type
An API adds a new optional interpretation for a previously unclassified event. A tolerant client preserves the raw record and shows an unknown label. A strict client crashes because its enum switch assumes only three values. Test that older readers can retain useful evidence even when they do not understand the new classification.
Use contract tests
Exercise representative old clients against the new response and the new client against the old response where rollout overlap matters. Include missing fields, explicit null and unknown values. Publish a new payload version when meaning or type must change. Do not assume that web, mobile and worker consumers will all deploy simultaneously.
A practical acceptance test
Run an older reader against a response with a new optional field and an unknown activity enum. It should preserve useful evidence under its fallback contract. Then remove a field that the new client treats as optional and verify compatibility with the old server response. Exact integer strings must not silently change into rounded numeric values.
Questions about the topic
Frequently asked questions
Is every added field backward-compatible?
No. Strict consumers or new required request fields can still break.
Should unknown enum values crash an evidence reader?
Prefer a defined fallback that preserves the underlying record when safe.
Standards & technical documentation