Designing APIs with Claude Code
Claude can design API contracts but needs the right inputs. Here's what to give it and what to verify before you build the implementation.
API design is one of the places where Claude's output is genuinely useful before any code is written. Having Claude draft the contract, endpoint structure, and request/response shapes means you can review the design on paper before committing to an implementation.
Start with consumers, not endpoints
The most common API design mistake is designing from the server side out. You think about what data you have and create endpoints to expose it. The result is an API that's technically complete but awkward to use.
Claude can help flip this. Give it the client use cases: "The mobile app needs to show a user's dashboard with their profile, recent activity, and notification count. It should load in a single request." Claude will design endpoints that serve those needs, rather than endpoints that mirror the database schema.
What to include in the API design prompt
- Who's calling this API (mobile app, web frontend, third-party integrations)
- The specific actions those callers need to perform
- Expected request volumes and latency requirements
- What the underlying data looks like
- Any constraints (auth requirements, versioning needs, backward compatibility)
Without the consumer use cases, Claude defaults to CRUD endpoints that mirror the data model. That's a reasonable starting point but rarely the right design for real usage patterns.
Validate the contract before implementing
Once Claude produces a draft API contract, I review it against the consumer use cases before writing any implementation code. Specifically:
- Can each use case be satisfied with the proposed endpoints?
- Are there any cases that require multiple round trips that could be a single call?
- Are the response shapes going to be awkward for the clients to consume?
- Are there missing error cases?
API design is much cheaper to change on paper than after the implementation exists. Claude can generate a revised design in seconds. Refactoring an implemented API takes hours and may require coordinating with API consumers.
Use Claude to generate the OpenAPI spec
Once the design is confirmed, Claude can generate the full OpenAPI spec. This is tedious to write by hand and Claude handles it well. The spec becomes the source of truth for the implementation and client code generation.
Ask for the spec before the implementation. Having the contract documented first keeps the implementation focused and makes it easier to verify the code matches the design.