How to Build a REST API with Claude Code

To build a REST API with Claude Code, you need to make the structural decisions before you write any prompts: framework, folder layout, error format, auth approach, database models.

Describe those decisions once in a project file and Claude Code builds consistently from there: routes, models, middleware, and tests, in the order you specify. This guide covers the complete process for a production-ready REST API.

Key Takeaways

• Define the API contract before prompting: Writing out your endpoints before giving Claude Code tasks produces far cleaner code than asking it to figure out the structure itself.
• Express and FastAPI are the strongest choices: Both frameworks are heavily represented in Claude's training data, making generated code more reliable.
• Database models come before routes: Claude Code builds routes that match the schema. Building routes first creates mismatches that require rework.
• Auth middleware is not optional: Protected endpoints need auth validation before going live. Adding auth after the fact requires touching every protected route.
• Claude Code generates OpenAPI docs from code: Ask for documentation after building the routes. It reads the implementation and produces accurate output.
• Test each route immediately after generating it: Testing after all routes are built produces lower coverage and harder debugging than testing route by route.

AI App Development

Your Business. Powered by AI

We build AI-driven apps that don’t just solve problems—they transform how people experience your product.

Let's talk

What Stack Should You Use for Your API?

Node.js + Express is the most reliable choice for general-purpose APIs built with Claude Code. Python + FastAPI is the best choice when the API involves data processing or ML inference.

Stack choice affects output reliability. Choose the framework with the most documentation in Claude Code's training data.

• Node.js + Express: The most common choice. Claude Code generates correct middleware and routing patterns reliably. Easy deployment to Vercel or Railway.
• Python + FastAPI: The best option for APIs using data processing or ML model inference. Type annotations produce clean output and automatic Swagger docs are built in.
• Node.js + Fastify: A valid Express alternative for performance-sensitive APIs. Less represented in Claude Code's training data, so output may require more review.
• Next.js API routes: If the API is consumed by one Next.js frontend only, building routes inside the same project reduces complexity significantly.

The full stack app context for the API covers how the API layer fits within a complete Next.js and Supabase build.

How Do You Set Up the Project and CLAUDE.md?

Initialise the project and install the framework before starting Claude Code. Then create CLAUDE.md with the folder structure, response shape conventions, and environment variable names.

CLAUDE.md is what makes Claude Code's output consistent across every subsequent session and prompt.

• Initialise first: Run npm init, install express, and install TypeScript dependencies before starting Claude Code in the project directory.
• Folder structure in CLAUDE.md: Specify routes/, middleware/, models/, and tests/ so Claude Code places generated files in the correct locations.
• Response shape conventions: Define the response envelope in CLAUDE.md: "all responses use { data, error, status }." This makes error handling consistent across every route.
• Environment variable names: List DATABASE_URL, JWT_SECRET, and PORT in CLAUDE.md so all generated code references them by the correct names.
• TypeScript strict mode: Prompt Claude Code to configure tsconfig.json with strict mode enabled. Strict TypeScript catches more error categories during generation.

One well-written CLAUDE.md file prevents most of the inconsistency issues that come from building a multi-route API across multiple sessions.

How Do You Design the Database Models?

Write a data model specification before prompting for any routes. Claude Code translates entity definitions, field types, and relationships accurately into schema code when given explicit input.

The ordering here matters. Schema before routes is the single most important sequencing rule in this guide.

• Write the spec first: List your entities, their fields and types, and their relationships. Claude Code translates this directly into clean schema code.
• Prisma for TypeScript/Node: Claude Code generates very clean Prisma schema syntax and client usage. Prompt for the schema file first, then the client utility, then the migration.
• SQLAlchemy for FastAPI/Python: The standard ORM for Python APIs. Drizzle is a modern TypeScript alternative to Prisma for teams that prefer it.
• Generate in sequence: Ask for the schema file first, then the database client utility, then the migration. Do not request all three at once.

For direct Postgres work without an ORM, the Postgres MCP server for Claude Code lets Claude Code query and inspect your Postgres database from the terminal.

• Explicit cascade behaviour: Tell Claude Code exactly what you want on delete ("on user delete, cascade delete all posts"). It generates the correct constraint syntax when behaviour is specified.

How Do You Build and Structure the API Endpoints?

Start with the API contract written as comments or a spec file. Generate routes one resource at a time, not all at once. Add input validation to every route that accepts a request body.

Claude Code builds better routes when it has a clear blueprint. Give it the contract before asking for code.

• Write the contract first: List each endpoint as a spec before prompting: POST /users, GET /users/:id, PUT /users/:id, DELETE /users/:id.
• One resource at a time: Ask Claude Code to build all routes for one entity, review them, then move to the next. This keeps context focused.
• Input validation on every route: Instruct Claude Code to add Zod for TypeScript routes or Pydantic for FastAPI. Validation belongs at the route level, not inside business logic.
• Consistent error responses: Define the error response shape in CLAUDE.md and ask Claude Code to use it everywhere. Inconsistent formats break API clients.
• Explicit HTTP status codes: Prompt Claude Code if you want specific codes. It defaults to sensible choices but follows explicit instructions for 201, 204, and 422 responses.

Review each resource's routes fully before moving to the next one. Catching a routing mistake at this stage costs minutes. Catching it after auth is wired costs an hour.

How Do You Add Auth Middleware?

Auth must be middleware, not inline logic. Ask Claude Code to write a reusable verifyToken middleware function and apply it to all protected routes.

Adding auth after routes are built means touching every protected route. Build the middleware first, apply it second.

• Middleware, not inline logic: A reusable middleware function is easier to maintain and update than auth logic repeated inside each route handler.
• JWT verifyToken middleware: Prompt Claude Code to create middleware that validates the Authorization: Bearer <token> header, extracts the user ID, and attaches it to req.user.
• Supabase auth option: For Supabase stacks, prompt Claude Code to use getUser() to validate session tokens. This integrates with the same auth system as the frontend.
• Role-based access control: After basic auth, ask Claude Code to create a requireRole middleware that checks req.user.role and returns 403 if the role does not match.

If this API is part of a SaaS product, the SaaS MVP build with Claude Code covers how auth integrates with user management and plan gating end-to-end.

How Do You Generate API Documentation with Claude Code?

Ask Claude Code to generate an OpenAPI specification after the routes are built. It reads the route files and produces accurate documentation that matches the actual implementation.

Documentation generated from code stays accurate. Documentation written alongside code drifts within weeks.

• OpenAPI spec generation: After building routes, ask Claude Code to produce an openapi.yaml or swagger.json. It reads the route files and generates accurate output.
• FastAPI handles this automatically: FastAPI generates a /docs endpoint from type annotations. Prompt Claude Code to ensure all parameters and return types are annotated.
• Node/Express setup: Prompt Claude Code to install and configure swagger-jsdoc and swagger-ui-express. It generates JSDoc comments for each route and serves the Swagger UI.
• README generation: Ask Claude Code to write the API README with setup instructions, environment variable list, and example curl commands. Regenerate it after adding new routes.

For a deeper guide to keeping documentation in sync with code changes, automated API documentation with Claude Code covers the full approach. For frontend teams consuming the API, connecting a React dashboard to the API shows the client-side integration pattern.

How Do You Test the API with Claude Code?

Ask Claude Code to write integration tests for each route immediately after generating it. Testing after all routes are built reduces coverage and increases debugging time.

Most developers skip testing until the end. That approach produces less coverage and harder debugging than testing route by route.

• Test immediately after each route: Writing tests for a route right after generating it keeps context focused and coverage complete.
• Test framework at setup time: Configure Jest with supertest for Node/Express or pytest with httpx for FastAPI at project setup, not as an afterthought.
• Four tests per route: Valid request with correct data, invalid data returning a validation error, missing auth token returning 401, and correct auth with insufficient permissions returning 403.
• Use real error output: When a test fails, give Claude Code the exact error message. It fixes the implementation or the test correctly with precise input.
• Database teardown hooks: Prompt Claude Code to write test setup and teardown that seeds test data and cleans the database after each test run.

Tests that pollute shared state produce inconsistent results. The teardown hook is not optional.

Conclusion

Building a REST API with Claude Code is fastest when structure comes before code.

The sequence is data model first, then routes, then auth middleware, then tests. Developers who finish with clean, well-tested APIs gave Claude Code a clear contract to build against. Developers who asked it to figure out the design produced rework.

Before your first prompt, write out your endpoint list: method, path, request body fields, and expected response shape. Paste that into CLAUDE.md as the API contract. That document is what Claude Code builds against.

AI App Development

Your Business. Powered by AI

We build AI-driven apps that don’t just solve problems—they transform how people experience your product.

Let's talk

Need a Production-Ready API Built to Specification?

Designing a REST API correctly means making the right sequencing decisions before writing a line of code. Most teams who struggle with Claude Code API builds skipped the contract phase and paid for it in rework.

At LowCode Agency, we are a strategic product team, not a dev shop. We design the data model, build authenticated endpoints, generate documentation, and deploy to production using the same structured sequence this guide describes.

• API contract design: We write the endpoint specification, request and response shapes, and error format before any code is generated.
• Database schema build: We design and generate the Prisma or SQLAlchemy schema with correct relationships and cascade behaviour before routes are touched.
• Route generation and review: We build routes one resource at a time and review each one before moving forward, keeping Claude Code's context clean.
• Auth middleware setup: We implement JWT or Supabase auth as reusable middleware, applied consistently across all protected endpoints.
• Documentation generation: We produce OpenAPI specifications and README files from the code, not alongside it, so documentation stays accurate.
• Test coverage by route: We write integration tests for each route immediately after generation, covering the four standard test cases per endpoint.
• Full product team: Strategy, design, development, and QA from one team, treating your API as a product with a defined spec and a production deployment target.

We have built 350+ products for clients including Coca-Cola, American Express, and Medtronic.

If you need custom API development with LowCode Agency and want it built to specification the first time, talk to our team.