API Design

Resources

scripts/
  api-checklist.sh
references/
  api-style-guide.md

API Design

This skill guides you through designing and implementing API endpoints using GoodVibes precision and project engine tools. Use this workflow when building REST APIs, GraphQL resolvers, tRPC procedures, or any HTTP endpoint.

When to Use This Skill

Load this skill when:

• Building a new API endpoint or route
• Implementing request validation or middleware
• Designing error response formats
• Generating API documentation
• Syncing types between frontend and backend
• Migrating between API paradigms (REST to tRPC, etc.)

Trigger phrases: "create an API", "build endpoint", "implement route", "add validation", "GraphQL resolver", "tRPC procedure".

Core Workflow

Phase 1: Discovery

Before implementing anything, understand existing patterns.

Step 1.1: Map Existing Routes

Use get_api_routes to discover all API endpoints in the project.

mcp__plugin_goodvibes_project-engine__get_api_routes:
  project_root: "."  # or specific path

What this reveals:

• Route file locations and naming conventions
• HTTP methods in use (GET, POST, PUT, DELETE, PATCH)
• Route structure (flat vs nested)
• Framework patterns (Next.js App Router, Express, Fastify, tRPC)

Step 1.2: Discover Patterns

Use discover to find middleware, validation, error handling, and auth patterns.

discover:
  queries:
    - id: middleware
      type: grep
      pattern: "(middleware|use\\()"
      glob: "**/*.{ts,js}"
    - id: validation
      type: grep
      pattern: "(z\\.|yup\\.|joi\\.|validator\\.)"
      glob: "**/*.{ts,js}"
    - id: error_handlers
      type: grep
      pattern: "(catch|try|Error|throw)"
      glob: "src/api/**/*.{ts,js}"
    - id: auth_patterns
      type: grep
      pattern: "(auth|jwt|session|bearer|getServerSession)"
      glob: "**/*.{ts,js}"
  verbosity: files_only

What this reveals:

• Validation library in use (Zod, Yup, Joi)
• Error handling patterns
• Authentication middleware
• Existing route structure

Step 1.3: Read Key Files

Read 2-3 representative route files to understand implementation patterns.

precision_read:
  files:
    - path: "src/api/users/route.ts"  # or discovered route
      extract: content
    - path: "src/lib/validation.ts"  # or discovered validation file
      extract: outline
  verbosity: standard

Phase 2: Decision Making

Choose the API paradigm that fits your needs. See references/api-style-guide.md for the full decision tree.

Quick Decision Guide

Consult references/api-style-guide.md for the REST vs GraphQL vs tRPC vs Server Actions decision tree.

Phase 3: Implementation

Step 3.1: Define Validation Schema

Create request validation using the project's validation library.

Example with Zod:

import { z } from 'zod';

export const createUserSchema = z.object({
  email: z.string().email(),
  name: z.string().min(2).max(100),
  role: z.enum(['user', 'admin']).default('user'),
});

export type CreateUserInput = z.infer<typeof createUserSchema>;

Best Practices:

• Validate all inputs (body, query params, headers)
• Use strict schemas (no unknown keys)
• Provide clear error messages
• Export inferred types for reuse

Step 3.2: Implement Route Handler

Write the route handler following project conventions.

Next.js App Router Example:

import { NextRequest, NextResponse } from 'next/server';
import { createUserSchema } from './schema';
import { db } from '@/lib/db';
import { getServerSession } from '@/lib/auth';

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

  // 2. Parse and validate input
  const body = await request.json();
  const result = createUserSchema.safeParse(body);

  if (!result.success) {
    return NextResponse.json(
      { error: 'Validation failed', details: result.error.flatten() },
      { status: 400 }
    );
  }

  // 3. Authorization check
  if (session.user.role !== 'admin') {
    return NextResponse.json(
      { error: 'Forbidden' },
      { status: 403 }
    );
  }

  // 4. Business logic
  try {
    const user = await db.user.create({
      data: result.data,
    });

    return NextResponse.json(user, { status: 201 });
  } catch (error) {
    console.error('Failed to create user:', error);
    return NextResponse.json(
      { error: 'Internal server error' },
      { status: 500 }
    );
  }
}

tRPC Example:

import { z } from 'zod';
import { protectedProcedure, router } from '../trpc';

export const userRouter = router({
  create: protectedProcedure
    .input(
      z.object({
        email: z.string().email(),
        name: z.string().min(2).max(100),
      })
    )
    .mutation(async ({ ctx, input }) => {
      if (ctx.session.user.role !== 'admin') {
        throw new TRPCError({ code: 'FORBIDDEN' });
      }

      return await ctx.db.user.create({
        data: input,
      });
    }),
});

Step 3.3: Write Using Precision Tools

Use precision_write to create route files, validation schemas, and types.

precision_write:
  files:
    - path: "src/app/api/users/route.ts"
      content: |
        import { NextRequest, NextResponse } from 'next/server';
        // ... [full handler implementation]
    - path: "src/app/api/users/schema.ts"
      content: |
        import { z } from 'zod';
        export const createUserSchema = z.object({ ... });
  verbosity: count_only

Phase 4: Error Handling

Standard Error Response Format

Maintain consistent error responses across all endpoints.

interface APIError {
  error: string;           // Human-readable message
  code?: string;           // Machine-readable error code
  details?: unknown;       // Validation errors or additional context
  trace_id?: string;       // For debugging in production
}

HTTP Status Code Guidelines:

• 200 - Success
• 201 - Created (POST)
• 204 - No Content (DELETE)
• 400 - Bad Request (validation error)
• 401 - Unauthorized (not authenticated)
• 403 - Forbidden (not authorized)
• 404 - Not Found
• 409 - Conflict (duplicate resource)
• 500 - Internal Server Error

Error Handling Pattern

try {
  // Business logic
} catch (error) {
  // Log for debugging (never expose to client)
  console.error('Operation failed:', error);

  // User-facing error
  return NextResponse.json(
    { error: 'Failed to process request' },
    { status: 500 }
  );
}

Never expose:

• Stack traces in production
• Database error messages
• File paths or internal structure
• Secrets or credentials

Phase 5: Documentation

Step 5.1: Generate OpenAPI Spec

For REST APIs, generate OpenAPI documentation automatically.

mcp__plugin_goodvibes_project-engine__generate_openapi:
  project_root: "."
  output_path: "docs/openapi.yaml"

What this generates:

• Route paths and HTTP methods
• Request/response schemas
• Authentication requirements
• Example requests/responses

If the tool doesn't exist or fails, manually document endpoints:

# In a routes.md file
POST /api/users
Description: Create a new user
Auth: Required (admin)
Body: { email: string, name: string, role?: 'user' | 'admin' }
Response 201: User object
Response 400: Validation error
Response 401: Unauthorized
Response 403: Forbidden

Step 5.2: Add JSDoc Comments

Document route handlers with JSDoc.

/**
 * Create a new user.
 * 
 * @requires Authentication (admin role)
 * @body {CreateUserInput} User data
 * @returns {User} Created user object
 * @throws {401} Unauthorized - Not authenticated
 * @throws {403} Forbidden - Not an admin
 * @throws {400} Bad Request - Validation failed
 */
export async function POST(request: NextRequest) {
  // ...
}

Phase 6: Type Safety

Step 6.1: Sync Frontend/Backend Types

Use sync_api_types to check type alignment.

mcp__plugin_goodvibes_project-engine__sync_api_types:
  backend_dir: "src/app/api"
  frontend_dir: "src/lib/api-client"

What this checks:

• Request types match between frontend and backend
• Response types are consistent
• No mismatched field names or types
• All endpoints have corresponding client code

Step 6.2: Export API Types

Expose types for client consumption.

// src/types/api.ts
export type { CreateUserInput, User } from '@/app/api/users/schema';

For tRPC, types are automatically inferred:

// Client code
import { trpc } from '@/lib/trpc';

const user = await trpc.user.create.mutate({
  email: 'test@example.com',
  name: 'Test User',
}); // Fully typed!

Phase 7: Validation

Step 7.1: Validate API Contract

Use validate_api_contract to verify responses match spec.

mcp__plugin_goodvibes_analysis-engine__validate_api_contract:
  spec_path: "docs/openapi.yaml"
  implementation_dir: "src/app/api"

What this validates:

• Response schemas match OpenAPI spec
• Status codes are correct
• Required fields are present
• Types are accurate

If the tool doesn't exist, manually test:

# Use curl or httpie to test endpoints
curl -X POST http://localhost:3000/api/users \
  -H "Content-Type: application/json" \
  -d '{"email":"test@example.com","name":"Test"}'

Step 7.2: Run Type Check

Verify TypeScript compilation.

precision_exec:
  commands:
    - cmd: "npm run typecheck"
      expect:
        exit_code: 0
        stderr_empty: true
  verbosity: minimal

Step 7.3: Run API Checklist Script

Use the validation script to ensure quality.

bash scripts/api-checklist.sh .

See scripts/api-checklist.sh for the complete validation suite.

Middleware Patterns

Implement authentication, CORS, and rate limiting middleware following the patterns in references/api-style-guide.md. Always use environment variables for security-sensitive configuration like CORS origins.

Testing

Test API endpoints with meaningful assertions covering success cases, validation errors, and authentication failures. See references/api-style-guide.md for testing patterns.

Common Anti-Patterns

DON'T:

• Trust client input without validation
• Expose database errors to clients
• Use GET for mutations
• Return different response formats per endpoint
• Skip authentication checks
• Ignore authorization (resource ownership)
• Use any types in route handlers
• Hardcode sensitive values (API keys, secrets)
• Return 200 for errors

DO:

• Validate all inputs with strict schemas
• Use consistent error response format
• Follow HTTP semantics (GET = read, POST = create, etc.)
• Implement proper authentication and authorization
• Use TypeScript for all API code
• Load secrets from environment variables
• Return appropriate status codes
• Log errors for debugging (don't expose them)

Quick Reference

Discovery Phase:

get_api_routes: { project_root: "." }
discover: { queries: [middleware, validation, auth], verbosity: files_only }
precision_read: { files: [route examples], extract: content }

Implementation Phase:

precision_write: { files: [route, schema, types], verbosity: count_only }

Validation Phase:

generate_openapi: { project_root: ".", output_path: "docs/openapi.yaml" }
validate_api_contract: { spec_path: "docs/openapi.yaml" }
sync_api_types: { backend_dir: "src/api", frontend_dir: "src/lib" }
precision_exec: { commands: [{ cmd: "npm run typecheck" }] }

Post-Implementation:

bash scripts/api-checklist.sh .

For detailed decision trees and framework-specific patterns, see references/api-style-guide.md.

Converted and distributed by TomeVault — claim your Tome and manage your conversions.