Review an API design
Grades an endpoint or schema against your own conventions, error shape and versioning, then ranks findings by the client pain each causes.
Last updated
Fill in the blanks
Assembled in your browser — nothing you type is stored or sent anywhere.
Your prompt
Model-agnostic — works in Claude, ChatGPT, Gemini or any AI chat.
Why this prompt works
- →Fixing the review order — consistency, error shape, versioning, client impact — targets the four places API designs most often quietly break, instead of producing a generic "looks good."
- →Asking for the client's-eye view surfaces a failure invisible from the schema alone: a technically valid design that still forces callers into extra round trips or manual joins.
- →The explicit escape hatch on unknown conventions stops the model from silently substituting generic REST best practices for this API's actual, possibly different, house style.
Part by part
- Existing conventions in this API: {{existing_conventions}}
- The single most important variable. Without it the review is graded against generic REST advice, which is often actively wrong for an established API.
- Check it in this order:
- An explicit sequence. Left to itself a model reviews whatever it notices first, which is usually surface naming rather than the client-facing consequences.
- the client's-eye view
- Shifts perspective deliberately. Most design problems are invisible from the server side and obvious the moment you write the client call.
- Rank findings by how much client pain they cause
- Forces prioritisation. An unranked list of twelve findings gets the trivial casing note the same weight as a breaking change.
- ask rather than grading the design against generic REST defaults
- The guard. Without it, a model asked about an unfamiliar API confidently applies conventions your API deliberately does not follow.
Common mistakes
Review this API design.Produces generic REST commentary — use plural nouns, return 201 on create — regardless of what the API already does. Advice that contradicts your established conventions is worse than none.
Is this endpoint RESTful?Invites a purity argument rather than a usability one. Whether a design is RESTful matters far less than whether a client can call it without three round trips.
Review this API design and suggest improvements.Without an ordering, findings arrive in the order they were noticed and unranked, so a casing nit sits alongside a backward-incompatible change with no signal about which matters.
Questions
What counts as conventions worth pasting?
Casing, pluralisation, how errors are shaped, how versioning works, and how pagination is expressed. Those five determine most review findings, and getting them wrong is what makes generic advice actively harmful.
Why review the error shape specifically?
Because it is the part most often designed last and least often designed consistently. Clients handle errors with shared code, so an endpoint that reports failure differently forces a special case into every consumer.
Can it judge backward compatibility?
Only against what you show it. It can spot obvious breaks such as a removed field or a changed type; it cannot know which clients exist or which fields they actually read, so treat that section as a checklist rather than an answer.
Is this a substitute for a human reviewer?
No — it is a way to arrive at review with the obvious problems already fixed. It is reliably good at consistency and at spotting awkward client flows, and it cannot weigh a design against a roadmap it cannot see.