API Version Compatibility Testing evaluates whether supported client and server versions can exchange data without breaking a consumer contract or changing business meaning. An additive field is not automatically safe: compatibility depends on the real consumers and the support policy.
Establish the version and support matrix
Record contract, client, and server versions, the support and deprecation timeline, and migration order from supplied project evidence. Build only the combinations that apply.
| Client and server pair | Evidence needed |
|---|---|
| Old client with old server | Baseline behavior and supported period |
| Old client with new server | Whether the client accepts new fields, values, and errors |
| New client with old server | Whether fallback or migration behavior is supported |
| New client with new server | Target contract and consumer expectations |
Keep unsupported or unknown cells explicit. Do not fill them from convention or call the matrix complete because it lists four combinations.
Compare wire shape and business meaning
For each applicable direction, compare field type and requiredness, enum values, defaults, error payloads, and semantic units. Then check how the actual client reads and writes those fields. A shape-compatible amount in different units, a null handled as a default, or an unrecognized error can still change behavior.
A backward-compatibility claim needs client examples and a sourced support policy. Without them, mark the relevant cells unassessed instead of assuming clients ignore unknown fields.
Plan coexistence, deprecation, and rollback
Trace the old-client path while new servers or contracts are introduced, and the new-client path during migration. Identify which observations would support deprecation, what must remain available during coexistence, and which writes make rollback unsafe. Recommend dual-version or deprecation checks only where they follow the project support plan.
Record an AVC-## finding
Capture the version pair, change or field, source, trigger, expected consumer behavior, evidence state, impact and priority, owner role, close condition, and validation method. Distinguish an incompatible change from an unsupported or unknown combination.
Keep the review static and evidence-bounded
Compare supplied contracts, client samples, support notes, and prior reports. Do not execute tests, edit application assets, invent versions or behavior, or treat the candidate matrix as runtime coverage or release approval.
Related Skills
- API Schema Validation checks samples against one declared schema.
- API Contract Testing reviews broader producer/consumer agreements.
Install and invoke
Install the Skill:
npx skills add https://github.com/naodeng/awesome-qa-skills/tree/main/skills/en/testing-types/api-version-compatibility-testing -g
Invoke api-version-compatibility-testing with the supported versions, client examples, server contracts, support timeline, migration order, and rollback constraints.
Source
Read the API Version Compatibility Testing prompt. It defines the AVC-## contract and the client/server version-matrix boundary.