The demo goes well. A new checkout request succeeds, the response looks right, and everyone moves on.

A week later, an older client fails because the request now requires a field it has never sent.

Nothing in the demo was fake. It simply answered a different question: does the new flow work with the new input?

An API review also needs to ask what changed for callers that did not update.

Put the change where reviewers can see it

Here is a small schema diff for a fictional checkout request:

 type: object
-required: [items]
+required: [items, currency]
 properties:
   items:
     type: array
     items:
       type: string
+  currency:
+    type: string
+    enum: [USD, EUR]

The demo can show a perfectly valid request with currency: "USD". The diff reveals the compatibility question immediately: what happens to a caller that sends only items?

If the server still accepts that request, the proposed schema may be wrong. If the server rejects it, you need a migration decision. Either way, the discussion is specific.

OpenAPI's Schema Object gives you a structured place to express these rules. A diff of that structure helps reviewers focus on the actual contract change.

Review requests and responses from opposite directions

For a request, ask whether inputs that were previously accepted are still accepted.

For a response, ask whether an existing consumer can handle every newly possible output.

That second question catches changes that sound harmless in a release note. Adding a response enum value can surprise a client with an exhaustive switch. Making a field nullable can break code that calls string methods on it. Returning an additional object variant can invalidate assumptions even when the HTTP status stays the same.

Do not classify a change as safe merely because it adds rather than deletes something. Look at what a real consumer does with it.

Write the review around four questions

You do not need a long checklist for every small change. Start here:

  1. Which previously valid request might fail?
  2. Which newly possible response might an existing client mishandle?
  3. Did authentication, permissions, or error behavior change?
  4. What test or migration plan covers the affected caller?

If the answer is “none,” name the evidence. A compatibility test using the previous request shape is more useful than an assurance that the change should be fine.

For example, keep a fixture for the old checkout request. If you deliberately continue accepting it, test that behavior. If you deliberately stop accepting it, document the transition and test the new rejection behavior.

Separate formatting noise from behavior

A thousand-line document diff can hide a one-line breaking change.

Avoid mixing a large reformat with a contract update when you can. If a generator changes ordering, use a structured comparison or a focused view of the affected operation. Ask reviewers to inspect the request schema, response variants, and security requirements before reading prose edits.

Descriptions matter, too. Changing “UTC timestamp” to “local time” is a behavioral promise even if the schema still says string. A structural diff is a starting point, not a substitute for reading.

Powerduck brings OpenAPI editing, request debugging, and document preview into one workspace. Those views serve different parts of a review: the definition makes the rule explicit, the request helps exercise it, and the preview shows what the next developer will understand.

End the review with a decision

For the checkout example, a useful review comment might be:

Existing clients omit currency. Keep that request supported during the migration, document the server's behavior, and add a regression case using the old payload.

Or the team might choose a breaking change with a coordinated release. The point is to make that choice while the change is still easy to discuss.

A demo earns its place in the review. Pair it with the contract diff, and you can check both the new path and the callers already depending on the old one.

Which API change looked harmless in review but turned out to need a migration?