APIs for Product Managers
Running an API Design Review
A design review is not a status update. It is the cheapest moment in the entire lifecycle to catch a mistake, because nothing has been built yet.
Run a focused, 45–60 minute review before implementation starts, with the PM, the lead engineer, and — critically — someone who represents the caller's perspective (a solutions engineer, a partner-facing PM, or a developer advocate). Work through this list out loud.
Area | The question | The answer you don't want to hear |
|---|---|---|
Naming | Is every resource and field named consistently with the rest of our API? | "We named it differently because this team prefers it that way" |
Errors | Have we designed the error cases, not just the happy path? | "We'll figure out errors during implementation" |
Versioning | If we need to change this in six months, can we, without breaking existing callers? | "We haven't thought about that yet" |
Auth | Does this expose more data or capability than the stated use case actually requires? | "It was easier to just grant broad access" |
Idempotency | If this creates or changes something, what happens on an accidental retry? | "That shouldn't really happen" |
Docs | Who is writing the quickstart, and by when? | Silence |
Scale | What happens to this design at 100x our current expected volume? | "We'll deal with that if it happens" |
The goal of this meeting, like a data readiness review, is not to pass. It's to generate an honest "not yet" while it's still free. A design review that ends in unanimous agreement with no hard questions raised is usually a sign the room didn't do its job, not a sign the design was perfect.
YOUR MOVE THIS WEEK
Book this review for your next API change, before a single line of implementation code is written. Send the question table in advance so people show up with real answers instead of defensive ones.