API reviews often start with the producer’s OpenAPI file. A more honest starting point is the client adapters. Those adapters reveal the undocumented quirks: optional fields that are never optional in practice, status codes that mean different things across domains, and pagination flavours that force every new consumer to learn tribal knowledge.
We ask producers to inventory compensating logic in at least three high-traffic clients before proposing a redesign. If three teams independently normalise the same response, the contract is incomplete — not the clients.
Fixing the surface then becomes a negotiation about migration cost, not aesthetics. Publish the compensating patterns you intend to retire, give a window, and measure whether new clients still invent the same glue.
Architecture reviews earn trust when they treat consumer patches as primary evidence.