Beginner

API Design with AI

AI is useful for API design in two distinct ways: helping you think through design decisions before implementation, and generating OpenAPI specifications from requirements. Both have real value. The design exploration use case is underused — prompting AI to argue against your design choices surfaces problems you would otherwise discover after deployment. This page covers both workflows plus the emerging discipline of making APIs AI-readable for LLM tool use.

Prompting for API Design Decisions

1. Initial Endpoint Design

Design a REST API for [DESCRIBE THE DOMAIN — e.g., "a task management system where users can create projects and tasks"].

Requirements:

- [LIST KEY OPERATIONS — e.g., "users can create, read, update, and delete tasks"]

- [LIST CONSTRAINTS — e.g., "tasks belong to exactly one project"]

- [LIST ACCESS RULES — e.g., "users can only access their own projects"]

Output:

1. A list of endpoints (HTTP method + path + 1-line description)

2. For each endpoint: request body shape, response body shape, and error responses

3. Three design decisions you made and the alternative you considered for each

4. Anything I should clarify before implementing

The "design decisions + alternatives" request forces AI to make its assumptions explicit, so you can override the ones that don't fit your requirements.

2. Devil's Advocate Review

I have designed the following API. Act as a senior API architect reviewing it.

For each issue you find:

- Describe the problem

- Explain what will go wrong in practice

- Suggest a specific fix

Focus on: REST convention violations, missing error responses, versioning, pagination missing on list endpoints, authentication gaps, and any breaking change risks.

[PASTE YOUR API DESIGN OR OpenAPI SPEC]

This prompt surfaces problems before implementation. Ask for the review before writing a line of code.

Generating OpenAPI Specifications

OpenAPI generation prompt:

Generate an OpenAPI 3.1 specification for the following API endpoints.

For each endpoint include:

- A detailed description (not just a summary — explain when to call this endpoint and what it returns)

- All request parameters with types, required/optional status, and descriptions

- All possible response codes with response schemas (including 400, 401, 404, 500)

- At least one example request and response

Do not omit error responses — they are as important as success responses.

Endpoints: [DESCRIBE EACH ENDPOINT]

Rich OpenAPI descriptions are important for both human developers and LLMs using your API as a tool — thin descriptions cause both to misuse the API.

Making APIs AI-Ready for LLM Tool Use

As LLMs increasingly use APIs as tools (via MCP or function calling), API design must account for a new consumer: AI agents that read your spec to decide when and how to call your API. An AI-ready API has specific characteristics.

AI-ready API principles

Clear endpoint purpose: descriptions that say WHEN to call this endpoint, not just what it does
Unambiguous parameter names: user_id not id when there are multiple ID types
Complete error documentation: LLMs need error responses to know how to recover
Example values in schema: give the LLM concrete examples of valid parameter values
Relationship context: note which endpoints to call before others (e.g., "call /auth/token first")

Common design mistakes AI surfaces

List endpoints without pagination — LLMs will call them repeatedly trying to page
Missing 404 on GET — LLMs cannot distinguish "not found" from "server error"
Inconsistent naming: user_id in some endpoints, userId in others
Side effects on GET endpoints — violates REST semantics; agents assume GET is safe to call
No versioning — breaking changes with no migration path

Common API Design Patterns AI Can Generate

Pattern	Ask AI to generate	What to verify
Pagination	Cursor-based or offset pagination parameters and response envelope	Consistent with your existing patterns; correct default page size
Error responses	Standardised error schema with code, message, and details fields	Matches your existing error format; machine-readable error codes
Filtering / search	Query parameter conventions for filtering list endpoints	Consistent with other list endpoints in your API
Versioning	Versioning strategy options (URL, header, content negotiation) with trade-offs	Whether it fits your deployment and client update capabilities
Async operations	202 Accepted + polling or webhook pattern for long-running operations	Client capability to poll; timeout and failure handling

Checklist: Do You Understand This?

What does asking AI to list design decisions + alternatives accomplish that a direct design request does not?
Write a devil's advocate review prompt for an API endpoint: POST /users/delete that deletes a user account.
Why is a detailed OpenAPI description (not just a summary) important for APIs used by LLM tools?
What is an AI-ready API, and what five characteristics distinguish it from a traditional API design?
Why is a GET endpoint with side effects particularly dangerous when LLMs use your API?
What must you always include in an OpenAPI specification that many developers omit — and why do LLMs need it?