Designing Better APIs with AI: Patterns That Work

API design is one of those areas where getting it wrong is expensive. A bad internal API creates friction for every team that consumes it. A bad public API creates friction for every customer. And unlike implementation details, APIs are hard to change once people depend on them.

I’ve been using AI to improve my API design process for about four months now. The results have been uneven — some patterns save genuine time, others produce plausible-looking designs that fall apart under scrutiny. Here’s what I’ve learned.

Pattern 1: API Review Before Implementation

The single most valuable use of AI in my API design workflow is getting a review before I write any code. I describe the API I’m planning and ask for feedback:

The feedback I get is usually about 70% things I already knew and 30% things I’d have missed. The 30% is where the value is. On this specific example, the LLM pointed out:

• No idempotency key on POST /events — if a client retries a failed request, we’d process the batch twice. This is a classic API design mistake that’s expensive to fix after the fact.
• The batch_id in the response should also be in a Location header — REST convention for async operations.
• No rate limiting headers — X-RateLimit-Remaining, X-RateLimit-Reset.
• The GET /events endpoint needs a maximum time range — without it, a client could query years of data and kill the database.
• No versioning strategy — /v1/events or Accept: application/vnd.api+json;version=1.

All valid points. The idempotency key in particular saved us from a real problem — we implemented it from the start, and within a month we had a client that was retrying requests due to network timeouts. Without the idempotency key, we’d have had duplicate data.

Where this falls short: The LLM reviews against general API best practices, but it doesn’t know your specific constraints. It suggested cursor-based pagination (which is the right general advice), but for our use case, offset pagination was actually better because our consumers need to jump to arbitrary pages. You have to apply domain judgment to the generic recommendations.

Pattern 2: Schema Generation and Validation

Designing request/response schemas is tedious but important work. AI is good at generating initial schemas and finding inconsistencies:

The generated schemas are typically 80-85% correct. The most common issues:

• Overly strict validation — the LLM tends to add validation constraints that seem reasonable in isolation but don’t match real-world data. It might set maxLength: 100 on a description field when your actual data frequently exceeds that.
• Missing edge cases in enums — it’ll define status: enum [pending, completed, failed] but miss cancelled, timeout, or other states your system needs.
• Optimistic type definitions — it assumes clean data. In practice, you often need to handle legacy formats, optional fields that are sometimes null and sometimes absent, and so on.

Still, generating a schema that’s 85% right and then fixing it is much faster than writing from scratch.

Generating SDK Code

Once you have good schemas, you can have the LLM generate client SDK code:

The generated code is a reasonable starting point. I wouldn’t ship it directly — it always needs cleanup, better error messages, and adjustment to your specific auth patterns. But it shaves maybe 2-3 hours off the initial SDK development.

Pattern 3: Error Response Design

This is an underrated area where AI consistently adds value. Most APIs have terrible error responses because they’re an afterthought. I now explicitly design error responses with AI assistance:

Example output for the events endpoint:

// 400 Bad Request - Validation error
{
  "type": "https://api.example.com/errors/validation",
  "title": "Validation Error",
  "status": 400,
  "detail": "Event at index 3 has invalid timestamp format",
  "instance": "/events",
  "errors": [
    {
      "field": "events[3].timestamp",
      "message": "Expected ISO 8601 format, got '2025-13-01' (month 13 does not exist)",
      "value": "2025-13-01"
    }
  ]
}

// 409 Conflict - Idempotency conflict
{
  "type": "https://api.example.com/errors/idempotency-conflict",
  "title": "Idempotency Key Conflict",
  "status": 409,
  "detail": "Idempotency key 'abc123' was already used for a different request body",
  "instance": "/events",
  "existing_batch_id": "batch_789xyz"
}

// 413 Payload Too Large
{
  "type": "https://api.example.com/errors/payload-too-large",
  "title": "Batch Size Exceeded",
  "status": 413,
  "detail": "Batch contains 1,247 events. Maximum is 1,000.",
  "instance": "/events",
  "max_batch_size": 1000,
  "actual_batch_size": 1247
}

The quality of the error messages — especially the detail field — is noticeably better than what most engineers would write under time pressure. “Expected ISO 8601 format, got ‘2025-13-01’ (month 13 does not exist)” is the kind of helpful error message that saves consumers hours of debugging.

Pattern 4: API Documentation Generation

Documentation is where AI gives the most consistent time savings. Once the API is designed and implemented, generating comprehensive docs is straightforward:

I then review and edit — usually adjusting about 15-20% of the content, mostly to add domain-specific context and fix subtle inaccuracies in the code examples. The code examples especially need testing; the LLM generates code that looks right but sometimes uses deprecated methods or gets parameter order wrong.

Pattern 5: Backward Compatibility Analysis

When modifying an existing API, I use the LLM to check for backward compatibility issues:

This has caught several near-misses. In one case, we were about to change a field from string to integer (it was always numeric, we were “fixing” the type). The LLM correctly identified this as a breaking change — existing consumers parsing it as a string would break. It suggested adding a new field with the integer type and deprecating the old string field, which is the right approach.

The limitation: The LLM can only check for compatibility issues it can infer from the spec. It can’t know that a specific consumer is using an undocumented behavior, or that changing the order of fields in a JSON response will break a consumer with a fragile parser. You need integration tests for those.

Anti-Patterns: What Didn’t Work

Letting AI Design the API from Scratch

“Design an API for event ingestion” produces generic, cookie-cutter results that don’t account for your specific requirements, constraints, or consumers. AI is great at reviewing and improving a design — it’s poor at originating one, because good API design requires deep understanding of the use cases.

Blindly Following Convention Suggestions

The LLM will always recommend REST best practices — HATEOAS, content negotiation, proper use of HTTP methods, etc. Some of these make sense for your API. Some don’t. We have an internal API where we intentionally use POST for queries (because the query parameters are too complex for a GET query string), and the LLM flags this every time. It’s not wrong to flag it, but it doesn’t understand that we made a deliberate tradeoff.

Generating APIs from Database Schemas

I tried feeding a database schema to an LLM and asking it to generate a CRUD API. The result was technically functional but terrible from a design perspective — it exposed internal database structure, had no meaningful abstractions, and was missing all the business operations that don’t map to simple CRUD.

API design should be driven by consumer use cases, not database structure. AI doesn’t change this.

My Current Workflow

1. Design first draft manually based on consumer needs and use cases
2. AI review for convention violations, missing error cases, security gaps
3. AI-generate schemas and error responses, then review and fix
4. Implement the API
5. AI-generate documentation, then edit for accuracy and domain context
6. AI backward-compatibility check for any modifications

The AI touches every step, but it never leads. I’ve found this to be the right balance — AI catches what I miss, but the design decisions remain mine.

You might also like

• Using AI to Refactor Legacy Code Without Breaking Everything
• Prompt Engineering for Developers: 7 Patterns That Actually Work
• 10 AI Coding Assistant Tips That Actually Save Me Hours

📦 Free: AI Code Review Prompt Pack — 10 prompts I use on 15+ PRs/week.

Newsletter: One practical AI workflow per week, plus templates I don’t publish here. Subscribe →