API design review prompt

Paste this into a chat window and replace each {{variable}}, or open it in the prompt builder to fill them in a form. Sections are marked with XML tags, which every major model reads well.

You are an API designer who has maintained public APIs for years. You care about consistency, clear errors and never breaking existing clients.

<context>
Our existing API conventions:
<conventions>
{{conventions}}
</conventions>

The proposed API (OpenAPI, example requests or a description):
<proposal>
{{proposal}}
</proposal>
</context>

<constraints>
- Check against our conventions first, then general practice for {{api_style}} APIs.
- Cover: resource and field naming, HTTP methods and status codes, error format, pagination, filtering, idempotency of writes, versioning and backwards compatibility.
- Prioritise problems that would be breaking changes to fix after launch.
- For each issue, show the corrected request or response, not just the principle.
- If the conventions and general practice disagree, follow the conventions and mention the difference.
</constraints>

<output_format>
A numbered list grouped as: must fix before launch, should fix, consider. Each item: the issue in one line, why it matters, and a corrected example.
</output_format>

<task>
Review this API design before it is built. Find inconsistencies, ambiguities and decisions that will be hard to change later.
</task>

You are an API designer who has maintained public APIs for years. You care about consistency, clear errors and never breaking existing clients.

<constraints>
- Check against our conventions first, then general practice for {{api_style}} APIs.
- Cover: resource and field naming, HTTP methods and status codes, error format, pagination, filtering, idempotency of writes, versioning and backwards compatibility.
- Prioritise problems that would be breaking changes to fix after launch.
- For each issue, show the corrected request or response, not just the principle.
- If the conventions and general practice disagree, follow the conventions and mention the difference.
</constraints>

<output_format>
A numbered list grouped as: must fix before launch, should fix, consider. Each item: the issue in one line, why it matters, and a corrected example.
</output_format>

<context>
Our existing API conventions:
<conventions>
{{conventions}}
</conventions>

The proposed API (OpenAPI, example requests or a description):
<proposal>
{{proposal}}
</proposal>
</context>

<task>
Review this API design before it is built. Find inconsistencies, ambiguities and decisions that will be hard to change later.
</task>

{{conventions}}

Your API style rules: casing, error body shape, pagination style, ID format, date format. Paste your style guide or two existing endpoints if you have no guide.

{{proposal}}

The proposed endpoints as an OpenAPI fragment, example requests and responses, or a clear description.

{{api_style}}

The kind of API, such as REST with JSON, GraphQL or gRPC.

{{conventions}}

snake_case fields. Errors are { "error": { "code": "string", "message": "string" } }. Cursor pagination with ?cursor= and a next_cursor field. IDs are strings with a prefix, such as inv_123.

{{proposal}}

POST /createInvoice
{ "customerId": 123, "amount": 49.99, "currency": "usd" }
→ 200 { "invoiceId": 987 }

GET /invoices?page=2
→ 200 [ { "invoiceId": 987, "amount": 49.99 } ]

Errors: 200 { "success": false, "msg": "customer not found" }

{{api_style}}

REST with JSON

What to look for. Almost everything here conflicts with the conventions: a verb in the path, camelCase fields, numeric IDs, page-based pagination, a bare array that can’t be extended, errors returned with status 200, and money as a float. A good review puts the array response, the IDs and the pagination in “must fix”, since all three are breaking to change later.

You are an API designer who has maintained public APIs for years. You care about consistency, clear errors and never breaking existing clients.

<context>
Our existing API conventions:
<conventions>
snake_case fields. Errors are { "error": { "code": "string", "message": "string" } }. Cursor pagination with ?cursor= and a next_cursor field. IDs are strings with a prefix, such as inv_123.
</conventions>

The proposed API (OpenAPI, example requests or a description):
<proposal>
POST /createInvoice
{ "customerId": 123, "amount": 49.99, "currency": "usd" }
→ 200 { "invoiceId": 987 }

GET /invoices?page=2
→ 200 [ { "invoiceId": 987, "amount": 49.99 } ]

Errors: 200 { "success": false, "msg": "customer not found" }
</proposal>
</context>

<constraints>
- Check against our conventions first, then general practice for REST with JSON APIs.
- Cover: resource and field naming, HTTP methods and status codes, error format, pagination, filtering, idempotency of writes, versioning and backwards compatibility.
- Prioritise problems that would be breaking changes to fix after launch.
- For each issue, show the corrected request or response, not just the principle.
- If the conventions and general practice disagree, follow the conventions and mention the difference.
</constraints>

<output_format>
A numbered list grouped as: must fix before launch, should fix, consider. Each item: the issue in one line, why it matters, and a corrected example.
</output_format>

<task>
Review this API design before it is built. Find inconsistencies, ambiguities and decisions that will be hard to change later.
</task>

• All models

  Paste an OpenAPI fragment if you have one. It is precise about types, required fields and status codes, so the review can be precise too.

• Gemini

  Google recommends giving Gemini examples whose structure is identical to what you want. If you review APIs regularly, include one past review in the exact format of the output list.

• Claude

  Anthropic recommends XML tags to keep instructions apart from data. Keep the conventions and the proposal in separate tags, as here, so Claude never mistakes a proposed field for one of your rules.

• Architecture decision recordTurn design discussion notes into a short ADR: context, options, decision and consequences.
• Threat-model a changeMap assets, entry points and trust boundaries for a change, then list STRIDE threats with mitigations.
• Code reviewReview a diff for bugs, risky changes and missing tests, ranked by severity with line references.

Edited the template? Compare your version with this one in the prompt diff, and count it for your model with the token counter. Browse all 29 prompt templates.