Turn an API change into explicit provider and consumer checks. Start from the actual contract and affected clients, then verify wire-level behavior rather than relying on generated types or a successful build. Default to local fixtures and existing test tools; this skill does not provision a testing service.
Do not use this as authorization to call production endpoints, bypass access controls or publish a new API version.
Identify the provider, transport, contract source and version, known consumers and the requested behavior. Read the real OpenAPI/JSON Schema/protobuf definition or documented examples and the corresponding server/client code. Record missing consumers and stale specifications as coverage gaps; do not invent interfaces or claim complete coverage from one client.
Keep these distinct: documented schema, actual provider output, generated client types and runtime parsing. A type assertion alone is not validation. Preserve the existing protocol and test runner instead of introducing a new platform by default.
Review fields, requiredness, nullability, enum values, status codes, headers, content type, pagination and error behavior. Inspect whether clients tolerate extra fields and unknown enum values. Even an added optional field can break a strict consumer. Explicitly identify affected versions and assumptions before calling a change compatible.
For events, include duplicate delivery, ordering and version envelopes. For request changes, check serialization and server validation as well as responses.
Use deterministic synthetic fixtures for:
Assert the behavior promised by the contract. Do not silently coerce malformed values or make the fixture match a defect just to get a passing test.
Run the existing schema validator against fixtures. Exercise the provider handler locally and pass its serialized result through the real consumer parser. Check failure cases reject or map errors as specified. Use an authorized isolated integration environment only when fixtures cannot establish the required property; report that boundary explicitly.
A mock verifies assumptions encoded in the mock. It does not establish that the real provider implements them. Record exact commands, fixture versions and observed outcomes separately from unrun checks.
Deliver the change classification, affected consumers, test matrix, observed failures, minimal reproduction and remaining coverage gaps. For a breaking change, propose versioning, a compatibility adapter or a staged migration with owners and rollback criteria. Deployment and consumer migration require their own task authorization.
Synthetic documented response:
{"id":"invoice-demo","amount_minor":1250,"currency":"EUR"}
Contract: id and currency are strings; amount_minor is a non-negative integer in minor units. This fixture does not represent an actual customer or payment.
| Fixture change | Expected check |
|---|---|
amount_minor becomes "1250" |
Runtime parser rejects the string; compile-time generated types alone cannot detect wire drift. |
amount_minor is missing or null |
Reject when the field is required and non-nullable. |
Extra display_label field |
Verify the consumer's documented extra-field policy before declaring compatibility. |
| HTTP error with an HTML body | Produce the declared transport/protocol error, rather than treating it as a valid invoice. |
Reusable prompt:
Review this API change against the actual contract and supplied client/server code.
List affected consumers and supported version combinations. Add local contract tests
for valid, missing, null, wrong-type and error responses with the existing runner.
Report checks actually run and any provider behavior still requiring integration proof.
@api-rate-limit-handler — bounded replay-safe retry behavior.@deprecation-and-migration — consumer migration and verified removal.@api-security-best-practices — authorization and validation controls.