Design Better REST APIs with Claude Code: Consistent Patterns from Day One

#claudecode #api #rest #typescript

API design decisions made early are hard to change later. Claude Code can help establish consistent REST API patterns across your codebase — if you give it the conventions to follow.

CLAUDE.md for REST API Conventions

## REST API Design Conventions

### URL Structure
- Resources in plural: `/users`, `/posts`, `/orders` (not `/user`)
- Nested resources max 2 levels: `/users/{id}/posts` (not deeper)
- Actions as verbs only when RESTful isn't clean: `/orders/{id}/cancel`
- API versioning in URL: `/api/v1/users`

### HTTP Methods
- GET: Read (never modify data)
- POST: Create new resource
- PUT: Full replacement of resource
- PATCH: Partial update
- DELETE: Remove resource

### Response Format
- Always return JSON with Content-Type: application/json
- Success responses: `{ data: T }` or `{ data: T[], pagination: {...} }`
- Error responses: `{ error: string, code?: string, details?: any }`
- Timestamps: ISO 8601 format (UTC)

### HTTP Status Codes
- 200: OK (GET, PUT, PATCH success)
- 201: Created (POST success)
- 204: No Content (DELETE success)
- 400: Bad Request (validation error)
- 401: Unauthorized (not authenticated)
- 403: Forbidden (authenticated but no permission)
- 404: Not Found
- 409: Conflict (duplicate, optimistic lock failure)
- 422: Unprocessable Entity (validation passes but business logic fails)
- 500: Internal Server Error

### Pagination
- Cursor-based for large datasets: `{ data: [], nextCursor: string }`
- Offset-based for small datasets: `{ data: [], total: int, page: int, limit: int }`
- Default limit: 20, max: 100

Asking Claude Code to Review API Design

Review this API endpoint design for REST conventions violations.

Check against our CLAUDE.md rules:
1. URL naming (plural, max 2 levels of nesting)
2. HTTP method correctness
3. Response format consistency
4. Status code appropriateness
5. Missing pagination for list endpoints

Endpoints:
GET /api/v1/user — get all users
POST /api/v1/user/create — create user
GET /api/v1/user/posts — get user's posts (no ID specified)
DELETE /api/v1/user/remove/{id} — delete user

Expected feedback:

/user → /users (plural)
/user/create → POST /users (no verb in URL)
Missing user ID in nested route
/user/remove/{id} → DELETE /users/{id} (no verb)

Generating CRUD Endpoints

Generate CRUD endpoints for the Post resource.
Follow the API conventions in CLAUDE.md exactly.

Post schema:
- id: string (UUID)
- title: string
- content: string
- authorId: string
- publishedAt: timestamp (nullable)
- createdAt: timestamp
- updatedAt: timestamp

Include:
- List posts (with pagination)
- Get single post
- Create post
- Update post (PATCH)
- Delete post
- Publish post action

Pagination Implementation

For cursor-based pagination:

Implement cursor-based pagination for the GET /users endpoint.
Requirements:
- Default limit: 20, max: 100
- Cursor: encrypted base64 of (created_at, id)
- Response format: { data: User[], nextCursor: string | null, hasMore: boolean }
- Work with Prisma

Input Validation with Zod

Generate Zod schemas for the POST /users and PATCH /users/{id} endpoints.

POST requirements:
- email: valid email format
- name: 1-100 chars, no leading/trailing spaces
- role: enum of 'admin' | 'user' | 'viewer'
- password: min 8 chars, must contain uppercase + number

PATCH requirements:
- All fields optional (partial update)
- Same validation when provided

API Documentation from Routes

Generate OpenAPI 3.0 YAML for these Express routes.
Include all request/response schemas based on the route handlers.

[paste the routes file]

Code Review Pack (¥980) includes /code-review which checks REST convention compliance automatically.

👉 prompt-works.jp

Myouga (@myougatheaxo) — Security-focused Claude Code engineer.

DEV Community