How to review an AI-written API response change without breaking clients

When an AI-written PR changes an API response, start with the clients that already consume it. Identify the exact field or behavior that changed, find every known consumer, and run at least one check using the old client against the new provider. An updated schema and passing provider tests are useful, but neither tells you how a deployed client will behave.

Suppose an agent changes total_cents to total in an order response while updating the web app in the same PR. The new app works with the new API. A mobile build already in users' hands may still read total_cents. The review question is whether that old build can make the same request after the server deploys, and what it does with the reply.

Write down the old and new wire behavior

Compare the response as a client sees it, not just the TypeScript type or serializer. Record the endpoint, status code, content type, and a representative body from the base and proposed head. Look for removed or renamed fields, changed types, new null values, enum changes, different nesting, and altered error responses. A field can keep its name while changing meaning: total might be cents in one version and a decimal amount in another.

Use an OpenAPI diff if the repository maintains an accurate spec. It gives you a map of contract changes, not a verdict. A spec can lag behind the handler, and a nominally additive field can still upset a client with strict response validation. Check the actual serialized response and the callers before labeling a change backward compatible.

In Review Assist, compare the original request in problem.user_asks with approach.requirements and the anchored tour of changed hunks. If the request was to add a display label but the response rename appeared along the way, ask why the rename belongs in this PR. The scope drift guide gives a way to separate necessary contract work from an opportunistic cleanup.

Find the clients that cannot deploy with the provider

Search for the old field name in this repository, generated clients, tests, and any known downstream services. Ask who owns clients outside the repository. Web code may deploy with the API, but a mobile app, SDK, scheduled job, or partner integration can remain on the old contract. Write down the supported client versions and deploy order. If nobody can identify the consumers, treat compatibility as an open question rather than assuming the search was complete.

For the order example, a compatible transition could return both total_cents and a clearly specified new field while consumers migrate, then remove the old field only under an agreed retirement plan. That is an option to evaluate, not a universal fix. If the fields can disagree, the provider needs one source of truth and a test for the mapping. If versioning is proposed instead, check how existing clients select their version and whether the old version actually remains served.

Check failures as well as success. A renamed error code, a newly nullable amount, or a changed status can break retry and fallback logic even when the happy-path screen looks right. Review the client branch that handles missing fields and malformed responses, including what the user sees and whether the operation can be retried safely.

Make API contract testing exercise the old caller

Keep a fixture or consumer contract for the old request and expected response, then run it against the proposed provider. Also run the current client against the new provider. If the service uses generated clients, regenerate them and inspect the generated diff, but keep a check from a previously released client: regeneration alone proves only that the new client understands the new schema.

For total_cents, a focused test should send the old request, assert the old field's value and unit, and cover the error response the client relies on. If compatibility is intentionally broken, the PR needs a version or rollout plan with an owner, a client migration path, and a date or condition for removing the old behavior. A green integration suite that only starts the latest web app beside the latest API leaves the deployed-client question unanswered.

Read verification.performed and verification.not_verified in the Intent Document against the final head commit. Review Assist can show which checks the agent says it ran and anchor the changed handler, schema, and client hunks. Its coverage check confirms that counted hunks have an explanation; it does not run consumer contracts or certify compatibility. The guide to what the check means covers that boundary.

Ask for the one piece of missing evidence

A useful review comment is: “The PR updates the web caller, but the old mobile build reads total_cents. Please show the response it receives from this head, add a contract test for that field and its unit, and name when the old field can be removed. If the mobile build cannot be tested here, list that gap and the owner of the rollout decision.”

Approve when the old and new wire behavior is explicit, the relevant consumers are accounted for, the old caller has been exercised against the proposed provider, and any intentional break has a rollout decision. That is the practical answer to an API response review: follow the value across the deploy boundary, then ask for evidence at the boundary that can fail.