Building a REST API with Claude Code Tutorial

Building REST APIs can feel overwhelming when you are managing routing, validation, testing, and documentation simultaneously. Claude Code offers a powerful workflow that accelerates API development from initial design to production-ready endpoints. This tutorial walks you through creating a complete REST API using Claude Code and its ecosystem of skills.

Setting Up Your API Project

Before writing code, establish a clean project structure. Create a new directory and initialize your project:

mkdir user-api && cd user-api
npm init -y
npm install express cors helmet

If you are using TypeScript, initialize the project differently:

npx create-typescript-api user-api
cd user-api

Claude Code works well with either approach. The key is having a clear project structure that Claude can understand and navigate.

Using Claude Skills for API Development

Several Claude skills accelerate REST API development. The tdd skill helps you write tests before implementation, following test-driven development principles. The supermemory skill lets you maintain context across complex multi-file API projects.

Load the tdd skill by typing:

/tdd

Then describe your endpoint requirements:

/tdd
Create a POST /users endpoint that accepts email, name, and password. 
Write validation for email format and password minimum 8 characters.

Claude generates tests first, then implements the route to satisfy those tests.

Defining Your API Specification First

A well-designed API begins with clear specification before implementation. Document your endpoints, request methods, and expected responses upfront:

Resource paths: /users, /products, /orders
HTTP methods: GET for retrieval, POST for creation, PUT/PATCH for updates, DELETE for removal
Request/response formats: JSON structures with field types
Status codes: 200 for success, 201 for created, 404 for not found, 400 for bad request

For Python-based APIs, FastAPI provides automatic documentation from type hints:

from fastapi import FastAPI, HTTPException
from pydantic import BaseModel
from typing import Optional

app = FastAPI()

class User(BaseModel):
    name: str
    email: str
    bio: Optional[str] = None

Claude Code translates these specifications into complete implementations regardless of framework—Express, FastAPI, or others.

Defining Your API Specification

A well-designed API begins with clear specification. Document your endpoints, request methods, and expected responses before writing implementation code:

Resource paths: /users, /products, /orders
HTTP methods: GET for retrieval, POST for creation, PUT/PATCH for updates, DELETE for removal
Request/response formats: JSON structures with field types
Status codes: 200 for success, 201 for created, 404 for not found, 400 for bad request

For Python projects, FastAPI provides a strong alternative to Express:

from fastapi import FastAPI, HTTPException
from pydantic import BaseModel
from typing import Optional
import uuid

app = FastAPI()

class User(BaseModel):
    name: str
    email: str
    bio: Optional[str] = None

Claude Code translates these specifications into code for either framework. Use the tdd skill to structure your development: write tests first, then implement to meet those tests.

Creating Your First Endpoint

Create a basic Express server with user management endpoints:

// server.js
const express = require('express');
const cors = require('cors');
const helmet = require('helmet');

const app = express();
app.use(express.json());
app.use(cors());
app.use(helmet());

const users = [];
let nextId = 1;

// GET /users - List all users
app.get('/api/users', (req, res) => {
  res.json(users.map(user => ({ ...user, password: undefined })));
});

// POST /users - Create a user
app.post('/api/users', (req, res) => {
  const { email, name, password } = req.body;
  
  if (!email || !name || !password) {
    return res.status(400).json({ error: 'Missing required fields' });
  }
  
  if (!/^[^\s@]+@[^\s@]+\.[^\s@]+$/.test(email)) {
    return res.status(400).json({ error: 'Invalid email format' });
  }
  
  if (password.length < 8) {
    return res.status(400).json({ error: 'Password must be 8+ characters' });
  }
  
  const user = { id: nextId++, email, name, password };
  users.push(user);
  res.status(201).json({ ...user, password: undefined });
});

// GET /users/:id - Get user by ID
app.get('/api/users/:id', (req, res) => {
  const user = users.find(u => u.id === parseInt(req.params.id));
  if (!user) {
    return res.status(404).json({ error: 'User not found' });
  }
  res.json({ ...user, password: undefined });
});

const PORT = process.env.PORT || 3000;
app.listen(PORT, () => console.log(`Server running on port ${PORT}`));

Testing Your API with the TDD Skill

The tdd skill transforms how you approach API testing. Activate it and describe comprehensive test scenarios:

/tdd
Write integration tests for all user endpoints. Test:
Successful user creation returns 201 with user data
Missing fields returns 400
Invalid email returns 400
Short password returns 400
GET /users returns user list without passwords
GET /users/:id returns 404 for non-existent user

Claude generates a test file using your preferred testing framework. The generated tests follow REST conventions and cover edge cases you might otherwise miss.

For a more comprehensive testing approach, load the tdd skill before writing any endpoint code. This ensures your implementation satisfies real requirements from the start.

Documenting Your API

API documentation is critical for team collaboration. The pdf skill can generate PDF documentation from your API specifications. First, create an OpenAPI specification:

# openapi.yaml
openapi: 3.0.0
info:
  title: User Management API
  version: 1.0.0
  description: Simple REST API for user management

paths:
  /api/users:
    get:
      summary: List all users
      responses:
        '200':
          description: List of users
    post:
      summary: Create a user
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required: [email, name, password]
              properties:
                email:
                  type: string
                name:
                  type: string
                password:
                  type: string
      responses:
        '201':
          description: User created

  /api/users/{id}:
    get:
      summary: Get user by ID
      parameters:
        - name: id
          in: path
          required: true
          schema:
            type: integer
      responses:
        '200':
          description: User found
        '404':
          description: User not found

Use the frontend-design skill if you need to build an admin dashboard for your API. While frontend-design focuses on visual interfaces, it can help you create API testing UIs or admin panels.

Connecting MCP Servers for Enhanced API Development

Model Context Protocol servers extend Claude’s capabilities for API work. The filesystem MCP server lets Claude read and write API configuration files. The HTTP MCP server enables Claude to make actual HTTP requests to test your running API.

Configure MCP servers in your Claude settings:

{
  "mcpServers": {
    "http": {
      "command": "npx",
      "args": ["@modelcontextprotocol/server-http", "--port", "3001"]
    }
  }
}

Once configured, Claude can test your running API directly within your session. Ask Claude to verify your endpoints are working:

Make a POST request to http://localhost:3000/api/users 
with {"email": "test@example.com", "name": "Test User", "password": "password123"}
and verify the response

Error Handling Best Practices

Production APIs need robust error handling. Add centralized error handling to your Express app:

// Error handling middleware
app.use((err, req, res, next) => {
  console.error(err.stack);
  res.status(500).json({ error: 'Internal server error' });
});

// 404 handler
app.use((req, res) => {
  res.status(404).json({ error: 'Endpoint not found' });
});

The tdd skill helps you write tests for these error scenarios too. Load it and describe error cases:

/tdd
Write tests for: 500 error on server exception, 404 on undefined routes, 
and proper error response format for all error types

Deployment Considerations

When deploying your API, consider environment variables for sensitive configuration. Use the supermemory skill to track deployment notes and environment-specific settings:

/smem
Add: Production deployment uses PORT 8080, requires HTTPS, 
database connection string in environment variable DATABASE_URL

Supermemory maintains persistent context across sessions, making it invaluable for tracking deployment details and environment configurations you return to repeatedly.

Summary

Building REST APIs with Claude Code combines traditional development practices with AI-assisted workflows. The tdd skill ensures testability from the start. MCP servers enable direct API testing. Skills like supermemory help maintain context across complex projects.

Your next steps: scaffold a new API project, load the tdd skill, and build one endpoint following test-driven development. The workflow becomes intuitive quickly, and the resulting APIs tend to be more reliable and maintainable.

Built by theluckystrike — More at zovo.one