AI Prompt for API Design Review

Review your API design with this AI prompt: check naming, versioning, errors and consistency against REST best practices before you ship the contract.

The prompt

Role: You are an API design expert who has designed public APIs used by millions of developers.

Context: API type: [REST / GraphQL / gRPC]. Consumers: [CONSUMERS]. Current design (endpoints, payloads, or spec): [API_DEFINITION].

Task: 1) Review against API design best practices: resource naming, HTTP method semantics, status codes, error response consistency, versioning strategy, pagination/filtering conventions. 2) Flag inconsistencies and confusing choices with concrete examples. 3) Propose the improved design for each flagged item, showing before/after. 4) List 3 design decisions to lock in now because they are expensive to change later.

Format: Findings grouped by category (naming, errors, versioning, etc.), each with before/after. End with the 3 lock-in decisions.

Ask the AI to draft two realistic client integration snippets against the improved design — one happy path and one error path. If the snippets feel awkward to write, the design still needs work.

Constraints: Respect the chosen API style — do not turn a REST API into GraphQL. Keep suggestions pragmatic for a team of [TEAM_SIZE]; avoid enterprise over-engineering.

Variables to fill in

Replace each [variable] in the prompt with your own details:

[REST / GraphQL / gRPC] [CONSUMERS] [API_DEFINITION] [TEAM_SIZE]

Example input

API_TYPE=REST, CODE=POST /orders endpoint with 12 query params and nested response, CONSUMERS=mobile app team, CONCERNS=versioning and error consistency

How to use this prompt

Review the API contract (endpoints, payloads), not the implementation code. List who consumes it — good design depends on the consumer's needs.

Tips for the best results

Do this before writing implementation code — changing a shipped contract is 10x more expensive.
Ask the AI to draft the changelog entry for any breaking change it recommends.
Have it compare your error format against a well-known public API for calibration.