Writing API specs is tedious. These ready-to-use templates turn any LLM into a spec-writing machine that produces consistent, reviewable results.
Generic prompts like "design my API" produce generic output — shallow endpoints, missing error handling, and no thought about versioning or rate limits. I've tested these API Design Prompts across Claude 3.5 Sonnet, GPT-4o, Gemini 1.5 Pro, and DeepSeek-V3. They work on all four, though Claude tends to produce the most thoughtful error handling while DeepSeek needs the strictest constraints.
Why generic prompts fail here
Most developers hit a wall because they ask for "an API design" without giving the model a contract. The LLM doesn't know your auth model, your data constraints, or whether you're building for mobile or server-to-server. So it invents everything — and invents it inconsistently.
The failure mode is predictable: you get a list of endpoints with no status codes, no pagination strategy, and no thought about idempotency. Then you spend an hour rewriting it. These templates fix that by forcing the model to fill in specific gaps rather than free-form architecting.
Template 1: The REST Resource Builder
This is your workhorse for new CRUD-heavy resources.
You are designing a REST API for a [RESOURCE_TYPE] system.
Generate a complete API design with the following constraints:
1. Base URL: [BASE_URL]
2. Auth: [AUTH_METHOD - e.g., Bearer JWT, API keys, OAuth2]
3. Rate limit: [RATE_LIMIT - e.g., 100 req/min per user]
For each endpoint, provide:
- HTTP method and path
- Request body schema (JSON) with field types and required/optional flags
- Success response schema (200/201) with example
- Error responses: 400, 401, 403, 404, 409, 429 — each with a JSON error body
- Pagination strategy (cursor or offset) with response envelope format
Also include:
- Idempotency key header support for POST/PUT endpoints
- Sort/filter query parameter conventions
- A versioning strategy (URI or header-based)
Output as a structured markdown document. Do not skip error responses.
Placeholders: [RESOURCE_TYPE] is the domain (e.g., "user billing"), [BASE_URL] is your actual host, [AUTH_METHOD] and [RATE_LIMIT] are your real constraints. The key line is "Do not skip error responses" — without it, LLMs will happily omit 409s and 429s.
Template 2: The Webhook Event Contract
Webhooks are where most API designs fall apart. This template forces explicit event schemas.
Design a webhook delivery system for [EVENT_DOMAIN] events.
Requirements:
- Events: [LIST_EVENTS - e.g., order.created, order.updated, order.cancelled]
- Delivery: POST to subscriber URL with HMAC signature in X-Signature header
- Retry policy: exponential backoff (30s, 5m, 30m, 6h), max 4 attempts
- Response: subscriber must return 2xx within 5 seconds
For each event, define:
1. The exact JSON payload schema (no nested optional fields unless marked)
2. The HMAC signing secret derivation method
3. A sample payload with realistic values
Also specify:
- How to handle duplicate deliveries (idempotency via event_id field)
- The dead-letter queue behavior after max retries
- How subscribers can replay missed events (endpoint contract)
Be explicit about timestamp format (ISO 8601 UTC) and versioning via event version field.
This works well because it pins down the three places webhooks fail: signature verification, retry semantics, and idempotency. Gemini 1.5 Pro handles this well; GPT-4o sometimes invents a retry policy that contradicts yours, so keep the constraints tight.
Template 3: The Backward-Compatible Migration
This is the hard one — extending an existing API without breaking clients.
I have an existing API endpoint: [METHOD] [PATH] with current response:
[PASTE_CURRENT_RESPONSE_JSON]
I need to add [NEW_FEATURE_DESCRIPTION] without breaking existing clients.
Design the migration strategy:
1. Propose 2-3 versioning approaches (additive fields, new endpoint, version header)
2. For each, show the exact before/after response JSON
3. Recommend one approach with a clear rationale (client impact, dev effort, deprecation path)
Then generate:
- The new response schema with deprecated fields marked [DEPRECATED]
- A transition timeline (how long to support old version)
- Error handling for clients sending old payloads
- A changelog entry format for this change
Constraint: No breaking changes for 12 months. All new fields must have defaults.
The magic here is the "before/after response JSON" requirement. It forces the model to think in terms of actual wire format changes, not abstract versioning philosophy. Claude 3.5 Sonnet gives the most pragmatic recommendations here; DeepSeek tends to over-engineer with too many options.
How to adapt these for your own codebase
Three adjustments make these templates sing:
- Paste real schemas. Replace
[RESOURCE_TYPE]with your actual table columns or existing TypeScript interfaces. The model needs concrete field names to produce useful output. - State your conventions once. Add a line like "We use snake_case for all fields and kebab-case for URLs" to the template. It saves you from cleaning up camelCase garbage later.
- Iterate with diffs. Don't accept the first output. Run the template, then follow up with "Change the pagination to cursor-based" or "Add a 422 for validation errors." LLMs are better at targeted edits than single-shot perfection.
Do these prompts work with any LLM?
Yes, but with caveats. Claude 3.5 Sonnet and GPT-4o produce the most complete output with these templates. Gemini 1.5 Pro is good but occasionally drops error response details. DeepSeek-V3 works but needs the strictest wording — it'll cut corners if you don't explicitly say "do not skip." All four respect the structured output format. If you're using a smaller local model, expect to run the template twice and merge the best parts.
The one adjustment that improves these prompts the most: add a single line demanding "Show all endpoints as a markdown table before the detailed sections." It forces the model to plan the full surface area before diving into specifics, which cuts down on missed endpoints and inconsistent naming across the design.