How I use Claude Code for API design — a complete workflow

Designing a good API is one of the hardest things in software engineering. You ship it once, and you're married to it forever. Breaking changes mean broken clients, angry users, and deprecation nightmares.

I've built APIs that haunted me for years — inconsistent naming, missing pagination, no versioning. Claude Code changed how I approach this.

Here's my exact workflow.

The problem with how most developers design APIs

Most APIs get designed in one of two ways:

1. Code-first: write the handler, figure out the contract later
2. Copy-paste: duplicate what you've seen elsewhere, inconsistencies included

Neither produces great APIs. The first gives you inconsistency. The second gives you someone else's mistakes.

Phase 1: Contract-first design

Before writing a single line of handler code, I give Claude Code the domain requirements and ask it to design the contract:

Design a REST API for a task management system. Requirements:
- Users can create, update, delete tasks
- Tasks have status: todo, in_progress, done
- Tasks can be assigned to users
- Support filtering by status and assignee
- Pagination required
- We use Express + PostgreSQL

Output OpenAPI 3.0 spec. Follow REST conventions strictly.
Think about edge cases: what happens when you delete a task with comments?
What about bulk operations?

This produces a full OpenAPI spec before any implementation. The LLM catches things I'd miss: what happens on conflict? What status codes for each error case? Is the naming consistent?

Phase 2: Consistency audit

Once I have a spec, I ask Claude to audit it for consistency:

Audit this OpenAPI spec for:
1. Naming consistency (camelCase vs snake_case, plural vs singular)
2. HTTP verb correctness
3. Status code correctness (201 for creates, 204 for deletes, etc.)
4. Pagination consistency across all list endpoints
5. Error response format consistency
6. Missing endpoints (CRUD gaps)

Flag every inconsistency with line number and suggested fix.

This is where sessions get long. A real API spec for a complex system is thousands of lines. Claude Code reads the entire thing and cross-references every endpoint for consistency.

This is exactly where I hit rate limits. An audit of a 2,000-line spec across 40 endpoints burns through tokens fast. Claude Code pauses mid-audit: "You've reached your usage limit."

For sessions like this, I use SimplyLouie — a $2/month Claude API proxy. Same models, no usage pauses. The audit runs to completion.

Phase 3: Generate the boilerplate

From this OpenAPI spec, generate:
1. Express route stubs with correct middleware placement
2. Joi/Zod validation schemas for each request body
3. JSDoc comments for each handler
4. Integration test structure (not the tests themselves — just describe/it stubs)

Don't implement business logic. Just the structure.

This gives me a skeleton that exactly matches my spec. No drift between documentation and implementation from day one.

Phase 4: Error handling design

Design a consistent error handling system for this API:
- All errors should have: code (machine-readable), message (human-readable), details (optional context)
- Map HTTP status codes to error codes
- Handle: validation errors, auth errors, not found, conflict, rate limit, server error
- Show me how to implement this as Express middleware
- Show the exact JSON shape for each error type

Poor error handling is the most common API sin. Clients get {"error": "something went wrong"} with a 500. This prompt forces a proper error taxonomy upfront.

Phase 5: Versioning strategy

This API is launching to external developers. Design a versioning strategy:
- Should we use URL versioning (/v1/) or header versioning?
- How do we deprecate endpoints without breaking clients?
- Write the deprecation middleware that adds Sunset headers
- What's the minimum notice period for breaking changes?

Most developers skip versioning until they need it. By then it's too late. Claude Code talks through the tradeoffs (URL vs header, date-based vs semver) and gives you a concrete implementation.

Phase 6: Generate the client SDK

From this OpenAPI spec, generate a JavaScript/TypeScript client SDK:
- Typed methods for each endpoint
- Automatic retry with exponential backoff
- Request/response interceptors for auth
- Comprehensive JSDoc

The SDK should make it impossible to call the API incorrectly.

Sessions generating a full typed SDK from a large spec are among the longest possible. This is another natural rate-limit moment — and another reason I use SimplyLouie for sustained API design work.

The complete prompt sequence

# 1. Design
"Design OpenAPI 3.0 spec for [domain] with these requirements: [list]"

# 2. Audit
"Audit this spec for consistency issues. Flag every inconsistency."

# 3. Generate stubs
"Generate Express route stubs from this spec. No business logic."

# 4. Error handling
"Design a consistent error handling system. Show Express middleware."

# 5. Versioning
"Design a versioning and deprecation strategy. Show implementation."

# 6. Client SDK
"Generate a TypeScript client SDK from this spec."

Results

APIs I've designed with this workflow:

• Zero naming inconsistencies — the audit catches them all before implementation
• Consistent error shapes — clients can write one error handler
• Complete OpenAPI docs — generated before any code exists
• SDK ships with the API — not six months later

The rate limit problem in long sessions

API design sessions are long. You're working with large specs, iterating on hundreds of endpoint definitions, generating boilerplate for dozens of routes.

Claude Code's usage limits hit at the worst moments — mid-audit, mid-generation. For sustained API design work, SimplyLouie solves this: $2/month, same Claude models, no mid-session pauses.

The API design workflow works. The rate limits don't have to.

---

SimplyLouie is a $2/month Claude API proxy. 7-day free trial. Start here.