Skip to main content
skill CX Codex

rest-api-design · curiositech — Claude Code skill for REST APIs

The rest-api-design skill guides REST endpoint design with Zod validation and OpenAPI docs. Use it when adding routes to a Next.js App Router project.

MIT 209 installs ★ 274 updated 2026-10-30

Install into Claude Code · Skills CLI (Vercel) All methods and platforms ↓
npx skills add curiositech/some_claude_skills --skill rest-api-design -a claude-code
Open on GitHub

What rest-api-design does

The skill lays out a route structure and Zod schemas for request bodies and responses. Its examples cover session checks, request throttling, error handling, and database access; a PHI access log is shown for sensitive records. It also describes query parameter validation and several schema patterns.

OpenAPI documentation is part of the workflow. The route examples target Next.js App Router, so they may not fit a project built around GraphQL, WebSockets, or Supabase Edge Functions. The sample wires throttling through createRateLimiter and accesses data through db.

Install with npx skills add curiositech/some_claude_skills --skill rest-api-design -a claude-code. The skill file is placed at ~/.claude/skills/rest-api-design/SKILL.md.

What it helps with

  • design a REST route for Next.js App Router
  • validate request bodies and query parameters with Zod
  • handle failures with suitable response codes
  • document an API route in OpenAPI

Example prompts for the agent

  • Create a REST route for this feature in Next.js App Router and validate its request with Zod.
  • Review the request and response schemas for this API, then document the route in OpenAPI.
  • Add a session check and request throttling to this handler.

How to install rest-api-design

1Skills CLI (Vercel)

npx skills add curiositech/some_claude_skills --skill rest-api-design -a claude-code

2Manually: put the files in place

~/.claude/skills/rest-api-design/SKILL.md

Copy the whole skill folder; for one project use .claude/skills/rest-api-design/

Step by step, with commands for each platform: How to install skills in Claude Code: five ways

Questions about rest-api-design

How do I install rest-api-design in Claude Code?

Run npx skills add curiositech/some_claude_skills --skill rest-api-design -a claude-code. The skill file is located at ~/.claude/skills/rest-api-design/SKILL.md.

What does rest-api-design do?

It guides REST route design, Zod-based data checks, and OpenAPI documentation. The examples also cover authentication, errors, and request throttling.

Can I use rest-api-design for GraphQL?

No. The skill focuses on REST APIs and calls for a different approach to GraphQL.

Source text

SKILL.md · MIT
---
name: rest-api-design
description: Design REST API endpoints with Zod validation and OpenAPI documentation. Use when creating new API routes, validating request/response schemas, or updating API documentation. Activates for
  endpoint design, schema validation, error handling, and API docs.
allowed-tools: Read,Write,Edit,Bash(npm:*,npx:*)
metadata:
  category: Code Quality & Testing
  tags:
  - api
  - code
  - validation
  - documentation
  pairs-with:
  - skill: api-architect
    reason: REST API design is a specific implementation of broader API architecture principles
  - skill: openapi-spec-writer
    reason: REST endpoints designed here are formalized as OpenAPI specifications for documentation
  - skill: form-validation-architect
    reason: Client-side form validation schemas should mirror API request validation for consistency
---

# REST API Design

This skill helps you design and implement REST API endpoints following project patterns with Zod validation and OpenAPI documentation.

## When to Use

✅ **USE this skill for:**
- Creating new REST API endpoints with Next.js App Router
- Designing request/response schemas with Zod
- Implementing proper error handling and status codes
- Adding rate limiting and authentication
- Generating OpenAPI documentation

❌ **DO NOT use for:**
- GraphQL APIs → different paradigm entirely
- Cloudflare Workers → use `cloudflare-worker-dev` skill
- Supabase Edge Functions → use Supabase docs
- WebSocket/real-time APIs → different patterns

## API Route Structure

```
src/app/api/
├── auth/           # Authentication endpoints
├── check-in/       # Daily check-in CRUD
├── chat/           # AI coaching chat
├── journal/        # Journal entries
├── admin/          # Admin-only endpoints
└── health/         # Health check
```

## Standard Route Template

```typescript
// src/app/api/[feature]/route.ts
import { NextRequest, NextResponse } from 'next/server';
import { z } from 'zod';
import { getSession } from '@/lib/auth';
import { createRateLimiter } from '@/lib/rate-limit';
import { logPHIAccess } from '@/lib/hipaa/audit';
import { db } from '@/db';

// 1. Define schemas
const RequestSchema = z.object({
  field: z.string().min(1).max(1000),
  optional: z.string().optional(),
  enumField: z.enum(['option1', 'option2']),
  number: z.number().int().positive(),
});

const ResponseSchema = z.object({
  id: z.string(),
  createdAt: z.string().datetime(),
});

// 2. Configure rate limiter
const rateLimiter = createRateLimiter({
  windowMs: 60000,    // 1 minute
  maxRequests: 30,    // 30 requests per window
  keyPrefix: 'api:feature',
});

// 3. Implement handlers
export async function GET(request: NextRequest) {
  // Auth check
  const session = await getSession();
  if (!session) {
    return NextResponse.json(
      { error: 'Unauthorized' },
      { status: 401 }
    );
  }

  // Rate limit
  const rateLimitResult = await rateLimiter.check(session.userId);
  if (!rateLimitResult.allowed) {
    return NextResponse.json(
      { error: 'Rate limit exceeded' },
      { status: 429, headers: rateLimitResult.headers }
    );
  }

  // Query data
  const data = await db.query.features.findMany({
    where: eq(features.userId, session.userId),
  });

  // Audit log (if PHI)
  await logPHIAccess(session.userId, 'feature', null, 'LIST');

  return NextResponse.json(data);
}

export async function POST(request: NextRequest) {
  // Auth check
  const session = await getSession();
  if (!session) {
    return NextResponse.json(
      { error: 'Unauthorized' },
      { status: 401 }
    );
  }

  // Rate limit
  const rateLimitResult = await rateLimiter.check(session.userId);
  if (!rateLimitResult.allowed) {
    return NextResponse.json(
      { error: 'Rate limit exceeded' },
      { status: 429, headers: rateLimitResult.headers }
    );
  }

  // Parse and validate body
  let body: unknown;
  try {
    body = await request.json();
  } catch {
    return NextResponse.json(
      { error: 'Invalid JSON' },
      { status: 400 }
    );
  }

  const parsed = RequestSchema.safeParse(body);
  if (!parsed.success) {
    return NextResponse.json(
      {
        error: 'Validation failed',
        details: parsed.error.issues.map(i => ({
          path: i.path.join('.'),
          message: i.message,
        })),
      },
      { status: 400 }
    );
  }

  // Create resource
  const [created] = await db.insert(features).values({
    id: generateId(),
    userId: session.userId,
    ...parsed.data,
    createdAt: new Date(),
  }).returning();

  // Audit log
  await logPHIAccess(session.userId, 'feature', created.id, 'CREATE');

  return NextResponse.json(created, { status: 201 });
}
```

## Zod Schema Patterns

### Basic Types

```typescript
import { z } from 'zod';

const Schema = z.object({
  // Strings
  name: z.string().min(1).max(100),
  email: z.string().email(),
  url: z.string().url(),
  uuid: z.string().uuid(),

  // Numbers
  count: z.number().int().positive(),
  rating: z.number().min(1).max(5),
  price: z.number().nonnegative(),

  // Booleans
  isActive: z.boolean(),

  // Dates
  date: z.string().datetime(),
  dateOnly: z.string().regex(/^\d{4}-\d{2}-\d{2}$/),

  // Enums
  status: z.enum(['pending', 'approved', 'denied']),

  // Arrays
  tags: z.array(z.string()).min(1).max(10),

  // Optional fields
  notes: z.string().optional(),
  metadata: z.record(z.string()).optional(),

  // Nullable
  deletedAt: z.string().datetime().nullable(),
});
```

### Advanced Patterns

```typescript
// Discriminated unions
const EventSchema = z.discriminatedUnion('type', [
  z.object({ type: z.literal('click'), x: z.number(), y: z.number() }),
  z.object({ type: z.literal('keypress'), key: z.string() }),
]);

// Refinements
const PasswordSchema = z.string()
  .min(12, 'Password must be at least 12 characters')
  .regex(/[A-Z]/, 'Must contain uppercase')
  .regex(/[a-z]/, 'Must contain lowercase')
  .regex(/[0-9]/, 'Must contain number')
  .regex(/[^A-Za-z0-9]/, 'Must contain special character');

// Transform
const DateSchema = z.string()
  .datetime()
  .transform(str => new Date(str));

// Preprocess (coerce types)
const NumberFromString = z.preprocess(
  val => typeof val === 'string' ? parseInt(val, 10) : val,
  z.number()
);
```

### Query Parameter Validation

```typescript
export async function GET(request: NextRequest) {
  const { searchParams } = new URL(request.url);

  const QuerySchema = z.object({
    page: z.coerce.number().int().positive().default(1),
    limit: z.coerce.number().int().min(1).max(100).default(20),
    sort: z.enum(['asc', 'desc']).default('desc'),
    status: z.enum(['all', 'active', 'archived']).optional(),
  });

  const query = QuerySchema.safeParse({
    page: searchParams.get('page'),
    limit: searchParams.get('limit'),
    sort: searchParams.get('sort'),
    status: searchParams.get('status'),
  });

  if (!query.success) {
    return NextResponse.json(
      { error: 'Invalid query parameters', details: query.error.issues },
      { status: 400 }
    );
  }

  const { page, limit, sort, status } = query.data;
  // Use validated params...
}
```

## Error Response Format

```typescript
// Standard error response
interface APIError {
  error: string;           // Human-readable message
  code?: string;           // Machine-readable code
  details?: ErrorDetail[]; // Validation details
}

interface ErrorDetail {
  path: string;
  message: string;
}

// Error responses
return NextResponse.json(
  { error: 'Not found', code: 'NOT_FOUND' },
  { status: 404 }
);

return NextResponse.json(
  {
    error: 'Validation failed',
    code: 'VALIDATION_ERROR',
    details: [
      { path: 'email', message: 'Invalid email format' },
    ],
  },
  { status: 400 }
);
```

## HTTP Status Codes

| Code | Use Case |
|------|----------|
| 200 | Successful GET, PUT, PATCH |
| 201 | Successful POST (created) |
| 204 | Successful DELETE (no content) |
| 400 | Invalid request/validation error |
| 401 | Not authenticated |
| 403 | Not authorized (authenticated but forbidden) |
| 404 | Resource not found |
| 409 | Conflict (duplicate, etc.) |
| 429 | Rate limit exceeded |
| 500 | Server error |

## OpenAPI Documentation

Update `docs/openapi.yaml` when adding endpoints:

```yaml
paths:
  /api/feature:
    get:
      summary: List features
      tags: [Features]
      security:
        - cookieAuth: []
      parameters:
        - name: page
          in: query
          schema:
            type: integer
            default: 1
        - name: limit
          in: query
          schema:
            type: integer
            default: 20
            maximum: 100
      responses:
        '200':
          description: Success
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/Feature'
        '401':
          $ref: '#/components/responses/Unauthorized'

    post:
      summary: Create feature
      tags: [Features]
      security:
        - cookieAuth: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CreateFeatureRequest'
      responses:
        '201':
          description: Created
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Feature'
        '400':
          $ref: '#/components/responses/ValidationError'
        '401':
          $ref: '#/components/responses/Unauthorized'

components:
  schemas:
    Feature:
      type: object
      properties:
        id:
          type: string
          format: uuid
        name:
          type: string
        createdAt:
          type: string
          format: date-time
      required: [id, name, createdAt]

    CreateFeatureRequest:
      type: object
      properties:
        name:
          type: string
          minLength: 1
          maxLength: 100
      required: [name]

  responses:
    Unauthorized:
      description: Not authenticated
      content:
        application/json:
          schema:
            type: object
            properties:
              error:
                type: string
                example: Unauthorized

    ValidationError:
      description: Validation failed
      content:
        application/json:
          schema:
            type: object
            properties:
              error:
                type: string
              details:
                type: array
                items:
                  type: object
                  properties:
                    path:
                      type: string
                    message:
                      type: string
```

## Route Handler Patterns

### Dynamic Routes

```typescript
// src/app/api/feature/[id]/route.ts
export async function GET(
  request: NextRequest,
  { params }: { params: Promise<{ id: string }> }
) {
  const { id } = await params;

  // Validate ID format
  if (!isValidUUID(id)) {
    return NextResponse.json(
      { error: 'Invalid ID format' },
      { status: 400 }
    );
  }

  const item = await db.query.features.findFirst({
    where: eq(features.id, id),
  });

  if (!item) {
    return NextResponse.json(
      { error: 'Not found' },
      { status: 404 }
    );
  }

  return NextResponse.json(item);
}
```

### Pagination

```typescript
interface PaginatedResponse<T> {
  data: T[];
  pagination: {
    page: number;
    limit: number;
    total: number;
    totalPages: number;
  };
}

async function getPaginated(page: number, limit: number) {
  const offset = (page - 1) * limit;

  const [data, [{ count }]] = await Promise.all([
    db.query.features.findMany({
      limit,
      offset,
      orderBy: desc(features.createdAt),
    }),
    db.select({ count: count() }).from(features),
  ]);

  return {
    data,
    pagination: {
      page,
      limit,
      total: count,
      totalPages: Math.ceil(count / limit),
    },
  };
}
```

## References

- [Zod Documentation](https://zod.dev)
- [Next.js Route Handlers](https://nextjs.org/docs/app/building-your-application/routing/route-handlers)
- [OpenAPI Specification](https://swagger.io/specification/)
- [Dub.co Zod Validation](https://dub.co/blog/zod-api-validation)

© curiositech · MIT · curiositech/some_claude_skills

Similar skills

All skills for Backend and APIs →

rest-api-design by other authors comes first.

rest-api-design aj-geddes The rest-api-design skill gives your agent rules for resource naming, HTTP methods, status codes and versioning when you build new endpoints or clean up old ones. CX Codex +1 2,100installs rest-api-design secondsky The rest-api-design skill hands your agent a set of REST conventions: resource names, HTTP methods, status codes and JSON response shape. Useful when you start a new API or want existing endpoints to match. CX Codex +1 607installs design-rest-api davila7 design-rest-api designs RESTful API architectures, endpoints, authentication flows, and OpenAPI documentation directly from project code. CX Codex +1 559installs rest-api-design-patterns manutej rest-api-design-patterns — a reference skill for designing REST APIs: resource modeling, versioning, pagination, HATEOAS and HTTP method semantics. CX Codex +1 527installs api-design travisjneuman api-design is a Claude Code skill with guidelines and templates for REST, gRPC, and tRPC APIs; it helps generate OpenAPI schemas and keep route naming consistent. CX Codex +1 170installs api-contract-design Rudolf S. api-contract-design is a Claude Code skill for designing and checking REST, GraphQL, or hybrid API contracts before implementation. CX Codex +1 ★ 587repo stars api-endpoint-scaffolder OneWave-AI api-endpoint-scaffolder — a skill that scaffolds REST endpoints from templates for Next.js App Router and Express: Zod schemas, status codes, error handling. CX Codex +1 317installs public-api-design-review Samuel Berthe public-api-design-review runs a REST API surface, shipped or still on paper, through an eight-part checklist and splits every finding into Must-change or Improvement. CX Codex +1 10,200installs

From the same set180

The whole set →
hipaa-compliance The hipaa-compliance skill guides PHI handling with audit logging, log sanitization, and session checks. Use it when coding features that touch health data. CX Codex +1 215installs web-wave-designer web-wave-designer — a skill that builds ocean waves, ripples, and underwater distortion for the web with SVG filters and CSS animation. Handy when a page needs a living water background. CX Codex +1 214installs test-automation-expert test-automation-expert — a test automation skill that covers strategy, framework setup, coverage gaps and flaky test debugging. Useful when a project needs tests from scratch or existing ones keep breaking. CX Codex +1 212installs very-long-text-summarization very-long-text-summarization — a Claude Code skill that digests books, handbooks and large codebases with hierarchical multi-pass extraction. It outputs a structured knowledge map, not a plain compressed retelling. CX Codex +1 210installs modern-auth-2026 modern-auth-2026 adds passwordless authentication patterns to your agent: WebAuthn passkeys, Google and Apple OAuth, magic links, and cross-device sync. CX Codex +1 208installs automatic-stateful-prompt-improver automatic-stateful-prompt-improver intercepts complex prompts to refine them via DSPy, APE, and OPRO techniques. Stores optimization outcomes in an MCP server to learn across sessions. CX Codex +1 207installs skill-coach skill-coach helps build and audit Agent Skills by checking activation, expert guidance, anti-patterns, and progressive disclosure. CX Codex +1 207installs maximalist-wall-decorator maximalist-wall-decorator guides bold interior wall decoration, gallery walls, and freehand paint techniques. Built for maximalist spaces embracing the "more is more" philosophy. CX Codex +1 206installs

Project sponsors

Companies that keep this analytics open