AI Prompts for API Design

Quick-Start (Copy This Right Now)

Picture this: you're a backend developer starting a new service. You've got a requirements doc, a whiteboard sketch, and a blank API spec file. The question "where do I start?" has no obvious answer — and the choices you make in the first hour will constrain every integration built on top of this API for the next three years.

Here's the AI prompt that cuts through the blank-page problem:

You are a senior API architect. Design a REST API for the following feature set.

Feature requirements:
[paste your requirements in plain English — bullet points work fine]

Constraints:
- Consumer: [who calls this API — mobile app, third-party developers, internal service]
- Auth: [JWT / API key / OAuth2 / session]
- Scale expectation: [rough requests per day]
- Versioning strategy: [URI versioning /v1/ or header versioning]

Deliver:
1. Resource hierarchy (the nouns — what are the core resources?)
2. Endpoint list with HTTP methods and URLs
3. Request/response schemas for each endpoint (JSON, with field names, types, and required/optional)
4. HTTP status codes for success and each error case
5. Pagination strategy for any collection endpoints
6. One design decision you made that isn't obvious — and why you made it

Use REST best practices: plural resource names, nested resources only where the relationship is ownership, no verbs in URLs.

What this does: Forces the AI into architect mode rather than code-generation mode — you get a reasoned API design with explicit trade-off explanations, not just a list of endpoints.

Understanding the Variables

The "consumer" field is the most important variable in the prompt. An API consumed by third-party developers needs backward-compatibility guarantees, comprehensive error messages with error codes, and stable versioning — because breaking changes destroy trust with external partners. An internal service API can be looser on all three, because you control both sides of the contract.

The "one design decision that isn't obvious" instruction is actually the most valuable part of this prompt. Most API design prompts produce technically correct designs without explaining the trade-offs. That explanation is what you actually need to evaluate whether the design fits your context.

⚡ Pro tip: After getting the initial design, follow up with: "What are the three places in this API design where a future requirement change would be most painful? How would you handle each?" This surfaces the brittleness before you build it in — and often changes two or three endpoint decisions.

Step-by-Step: AI Prompts API Design

Step 1: Start with resources, not endpoints. Most developers jump straight to "what are my endpoints?" The better question is "what are my resources?" Resources map to the nouns in your domain — orders, users, products, invoices. Endpoints are just operations on those resources.

Given these feature requirements: [paste], identify the core REST resources (nouns). For each resource, describe: what it represents, what fields it contains, and what other resources it relates to. Don't write any endpoints yet.

What this does: Separates the modeling problem from the routing problem — which produces cleaner designs and fewer URL structure regrets.

Step 2: Design the error contract before the happy path. This is the insight most API design guides skip. Your error contract — the structure of error responses, the error codes you use, the HTTP status code semantics — is what API consumers depend on most when things go wrong. Design it first.

Design the error response format for a REST API. Requirements:
- Must be parseable by API consumers to display user-facing messages
- Must include a machine-readable error code (not just HTTP status)
- Must include a correlation ID field for support requests
- Should include a documentation URL pointing to the error's explanation

Also define: which HTTP status codes we'll use and exactly what each means in this API (many APIs overuse 400 and 500 — be specific).

What this does: Establishes the error contract that all endpoint designs will follow — rather than each endpoint having ad-hoc error handling.

Step 3: Design for pagination from the start. Every collection endpoint will eventually need pagination. Design it now, not when you hit performance problems.

Design a cursor-based pagination scheme for a REST API. Requirements:
- Works with arbitrary sort orders
- Doesn't break when items are inserted or deleted between pages
- Response format should include: data array, next_cursor, has_more boolean
- Cursor should be opaque to clients (not a raw offset)

Explain why cursor-based pagination is preferable to offset pagination for this use case.

What this does: Gets you a pagination design that won't break under real traffic conditions — offset pagination breaks in subtle ways when data changes between requests, which is almost always.

⚠️ Common mistake: Designing an API in one shot without iterating. AI can generate a complete API spec quickly — but "quick" and "correct" aren't the same thing. Treat the first output as a draft and run follow-up prompts: "Critique this design for a developer who has to consume it without reading the source code."

⚡ Pro tip: Ask the AI to write a one-paragraph "consumer experience narrative" for each major operation: "As an API consumer, here's what I do to accomplish X." If the narrative sounds complicated or requires multiple round trips, the API design has a usability problem.

Pro-Level Variations

For GraphQL API design:

Design a GraphQL schema for the following requirements. Include: type definitions, query fields, mutation fields, and subscription fields if real-time updates are needed. For each mutation, explain whether it should be optimistic on the client side. Flag any N+1 query risks in the schema design.

For internal microservice APIs (gRPC):

Design a gRPC service definition (.proto file) for the following service requirements. Include: service definition, message types, streaming vs unary decisions for each RPC with rationale, and error status codes. Flag any fields that are likely to change in future versions and suggest oneof or reserved field strategies.

For webhook API design:

Design the webhook event schema for [system]. Include: event type naming convention, payload structure (with a standard envelope), retry strategy, signature verification approach, and idempotency guidance for consumers. Explain the trade-offs between fat payloads (all data in the event) vs thin payloads (event + fetch pattern).

Troubleshooting Common Issues

Problem: AI produces too many nested resource URLs. Fix: Add "avoid nesting resources more than two levels deep" and "prefer flat resource collections with filter parameters over deep nesting."

Problem: Inconsistent field naming. Fix: Add "use camelCase for all JSON field names" or "use snake_case" at the top of the prompt. Naming conventions must be explicit.

Problem: API design ignores versioning. Fix: Add "design versioning into every endpoint from day one. Assume v2 will exist."

Problem: Response schemas are too vague. Fix: Add "include example values for every field, not just types."

Your Turn

Take your next greenfield API and run the quick-start prompt before writing a single line of code. Then run the "three most painful future changes" follow-up. The hour you spend there will save weeks of migration work later.

Store the resulting spec prompt in PromptABCD — along with your team's standard error contract and pagination design. When you start the next API, you're not starting from scratch. You're starting from your own vetted ai prompts api design, tuned to your stack.

API Design Review Before Implementation

One of the highest-value uses of AI in API design: reviewing a design before implementation begins. A 30-minute design review can catch problems that would take days to fix post-implementation.

Review this REST API design from the perspective of a developer who has to build a client against it without access to the source code.

API spec:
[paste your proposed endpoint list and schemas]

Flag:
1. Any endpoints that would require multiple round trips for a common consumer use case (these should probably be combined)
2. Any response schemas that are inconsistent with each other (field naming, data types, structure)
3. Any missing endpoints that a consumer would logically need based on the resource model
4. Any error responses that aren't descriptive enough to act on
5. One thing you'd change if you were building the client

What this does: Forces an outside-in perspective — the view from the consumer, not the implementer. API design mistakes are almost always visible from the consumer side and invisible from the implementation side.

⚡ Pro tip: After this review, ask the AI to write a "consumer integration guide" — a 500-word document explaining how to accomplish the three most common tasks with the API. If the guide is confusing to write, the API design has a usability problem worth fixing before implementation. API usability problems discovered in a document are free to fix. The same problems discovered after client SDKs have been built are very expensive.

⚡ Pro tip: For REST APIs with complex filtering, ask the AI to design the query parameter strategy explicitly: 'Design the filtering and sorting query parameters for this collection endpoint. Consider: which fields are filterable, range filters vs exact match, how to handle multiple values, and pagination interaction with sorting.' Query parameter design is where API usability most commonly breaks down.

A well-documented API design — not just the spec, but the reasoning — is also one of the best onboarding documents for new team members. The decisions it captures are exactly the context that takes months to absorb otherwise.