/api-designer

name: memstack-development-api-designer
description: "Use this skill when the user says 'design API', 'API endpoints', 'REST API', 'API designer', 'route structure', 'API architecture', or is designing RESTful API routes, request/response schemas, and endpoint organization. Do NOT use for API security audits or database design."
version: 1.0.0
license: "Proprietary, MemStack™ Pro by CW Affiliate Investments LLC. See LICENSE.txt"

🔌 API Designer: Designing routes, validation, and handler patterns...

*Produces production-ready Next.js App Router API routes with auth guards, Zod validation, typed responses, and consistent error handling.*

Activation

When this skill activates, output:

`🔌 API Designer, Designing API routes and handlers...`

Then execute the protocol below.

| Context | Status | |---------|--------| | User says "design API" or "create API route" or "add endpoint" | ACTIVE | | User says "REST API" or "route handler" | ACTIVE | | Building a new feature that needs API routes | ACTIVE | | Designing webhook endpoints | ACTIVE | | Discussing API concepts or REST theory | DORMANT | | Working on frontend components (not API layer) | DORMANT |

Anti-patterns

| Trap | Reality Check | |------|---------------| | "Auth is handled by middleware" | Middleware can be bypassed. Every route handler must verify auth independently. | | "I'll validate input later" | Unvalidated input is the root of injection, type errors, and 500s. Zod first, logic second. | | "Return 200 for everything" | Status codes are the API contract. 401 vs 403 vs 404 vs 422 mean different things to clients. | | "Error details help debugging" | Stack traces and internal errors help attackers. Return safe messages, log details server-side. | | "Rate limiting is a nice-to-have" | Public endpoints without rate limits get abused within hours of deployment. | | "TypeScript types are documentation enough" | Types exist at build time. Zod schemas validate at runtime. You need both. |

Protocol

Step 1: Design Route Structure

Map features to Next.js App Router file paths:

app/
  api/
    auth/
      login/route.ts          POST   - authenticate user
      logout/route.ts         POST   - clear session
      callback/route.ts       GET    - OAuth callback
    organizations/
      route.ts                GET    - list user's orgs
                              POST   - create org
      [orgId]/
        route.ts              GET    - get org details
                              PATCH  - update org
                              DELETE - delete org
        members/
          route.ts            GET    - list members
                              POST   - invite member
          [memberId]/
            route.ts          PATCH  - update role
                              DELETE - remove member
        projects/
          route.ts            GET    - list projects
                              POST   - create project
    webhooks/
      stripe/route.ts         POST   - Stripe webhook
      github/route.ts         POST   - GitHub webhook

**Naming conventions:**

| Convention | Rule | Example | |------------|------|---------| | Resource names | Plural nouns | `/organizations`, `/projects` | | Dynamic segments | `[paramName]` camelCase | `[orgId]`, `[memberId]` | | Nested resources | Parent/child path | `/organizations/[orgId]/projects` | | Actions (non-CRUD) | Verb sub-path | `/auth/login`, `/reports/generate` | | Webhooks | `/webhooks/{provider}` | `/webhooks/stripe` |

**Output route table:**

Method  Path                              Auth    Description
GET     /api/organizations                 ✅     List user's organizations
POST    /api/organizations                 ✅     Create organization
GET     /api/organizations/[orgId]         ✅+org  Get organization details
PATCH   /api/organizations/[orgId]         ✅+org  Update organization
...
POST    /api/webhooks/stripe               🔑sig  Handle Stripe webhook

Step 2: Auth Guard Pattern

Every protected route starts with the same two-step auth chain:

import { getAuthContext } from '@/lib/auth';
import { verifyOrgAccess } from '@/lib/auth';
import { NextRequest, NextResponse } from 'next/server';

export async function GET(
  req: NextRequest,
  { params }: { params: { orgId: string } }
) {
  // Step 1: Authenticate: who is this user?
  const auth = await getAuthContext(req);
  if (!auth) {
    return NextResponse.json(
      { error: 'Authentication required' },
      { status: 401 }
    );
  }

  // Step 2: Authorize, can they access this org?
  const access = await verifyOrgAccess(auth.userId, params.orgId);
  if (!access) {
    return NextResponse.json(
      { error: 'Access denied' },
      { status: 403 }
    );
  }

  // Now proceed with business logic...
}

**Auth decision matrix:**

| Route Type | Auth Required | Org Check | Example | |-----------|--------------|-----------|---------| | Public | ❌ | ❌ | `GET /api/health` | | Authenticated | ✅ | ❌ | `GET /api/user/profile` | | Org-scoped | ✅ | ✅ | `GET /api/organizations/[orgId]/projects` | | Admin-only | ✅ | ✅ + role check | `DELETE /api/organizations/[orgId]` | | Webhook | 🔑 Signature | ❌ | `POST /api/webhooks/stripe` |

Step 3: Input Validation with Zod

Every route that accepts input validates it before any logic runs:

import { z } from 'zod';

// Define schema next to the route handler
const createProjectSchema = z.object({
  name: z.string().min(1).max(100),
  description: z.string().max(500).optional(),
  status: z.enum(['draft', 'active', 'archived']).default('draft'),
  settings: z.object({
    isPublic: z.boolean().default(false),
    tags: z.array(z.string().max(50)).max(10).default([]),
  }).optional(),
});

type CreateProjectInput = z.infer<typeof createProjectSchema>;

export async function POST(req: NextRequest) {
  // ... auth checks ...

  // Validate input
  const body = await req.json();
  const parsed = createProjectSc