Agent skill

api-design

Load PROACTIVELY when task involves building or modifying API endpoints. Use when user says "build an API", "add an endpoint", "create a REST route", "set up GraphQL", or "add tRPC procedures". Covers route design and file organization, request validation with Zod, response formatting, error handling patterns, middleware composition, authentication guards, rate limiting, pagination, and API documentation generation.

View SKILL.md on GitHub Repository
Stars 6
Forks 1

Install this agent skill to your Project

npx add-skill https://github.com/mgd34msu/goodvibes-plugin/tree/main/plugins/goodvibes/skills/outcome/api-design

Metadata

Additional technical details for this skill

tags
api rest graphql trpc endpoint route middleware validation
version
1.0.0
category
outcome

SKILL.md

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.

yaml
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.

yaml
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.

yaml
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:

typescript
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:

typescript
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:

typescript
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.

yaml
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.

typescript
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

typescript
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.

yaml
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:

yaml
# 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.

typescript
/**
 * 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.

yaml
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.

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

For tRPC, types are automatically inferred:

typescript
// 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.

yaml
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:

bash
# 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.

yaml
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
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:

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

Implementation Phase:

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

Validation Phase:

yaml
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
bash scripts/api-checklist.sh .

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

Recommended Agent Skills

Expand your agent's capabilities with these related and highly-rated skills.

mgd34msu/goodvibes-plugin

testing-strategy

Load PROACTIVELY when task involves writing tests, improving coverage, or test infrastructure. Use when user says "add tests", "write unit tests", "set up E2E testing", "improve coverage", or "add mocks". Covers Vitest/Jest unit tests, React Testing Library component tests, Playwright E2E tests, MSW API mocking, test organization and naming, fixture management, coverage targets and thresholds, snapshot testing, and CI integration.

6 1
Explore
mgd34msu/goodvibes-plugin

ai-integration

Load PROACTIVELY when task involves AI, LLM, or machine learning features. Use when user says "add AI chat", "implement streaming responses", "build a RAG pipeline", "add embeddings", or "integrate OpenAI". Covers chat interfaces, streaming with Vercel AI SDK, retrieval-augmented generation, vector search, embeddings pipelines, tool/function calling, and provider abstraction for OpenAI, Anthropic, and local models.

6 1
Explore
mgd34msu/goodvibes-plugin

payment-integration

Load PROACTIVELY when task involves payments, billing, or subscriptions. Use when user says "add payments", "integrate Stripe", "set up subscriptions", "add a checkout flow", or "handle billing webhooks". Covers Stripe, LemonSqueezy, and Paddle integration, checkout sessions, subscription lifecycle management, webhook verification and handling, customer portal, metered billing, refunds, and PCI compliance considerations.

6 1
Explore
mgd34msu/goodvibes-plugin

state-management

Load PROACTIVELY when task involves application state, data fetching, or form handling. Use when user says "manage state", "add data fetching", "set up Zustand", "handle form validation", or "add React Query". Covers server state (TanStack Query with caching, optimistic updates), client state (Zustand stores), form state (React Hook Form with Zod validation), URL state (search params, routing), and choosing between state solutions.

6 1
Explore
mgd34msu/goodvibes-plugin

database-layer

Load PROACTIVELY when task involves database design, schemas, or data access. Use when user says "set up the database", "create a schema", "add a migration", "write a query", or "set up Prisma". Covers schema design and normalization, ORM setup (Prisma, Drizzle), migration workflows, connection pooling, query optimization, indexing strategies, seeding, and transaction patterns for PostgreSQL, MySQL, SQLite, and MongoDB.

6 1
Explore
mgd34msu/goodvibes-plugin

component-architecture

Load PROACTIVELY when task involves designing or building UI components. Use when user says "build a component", "create a form", "add a modal", "design the layout", or "refactor this page". Covers component composition and hierarchy, prop design and typing, render optimization (memo, useMemo, useCallback), compound component patterns, controlled vs uncontrolled forms, file organization, and accessibility for React, Vue, and Svelte.

6 1
Explore

Didn't find tool you were looking for?

Be as detailed as possible for better results