# Scaffolding API Routes

> Reads API_Contracts.md artifacts and rebuilds the legacy Express routes as modern Next.js Route Handlers or Server Actions. Use when following a legacy audit artifact to scaffold out a new Express API routes.

- Skill: `googlecloudplatform/scaffolding-api-routes` (Agent Skill)
- Install (CLI): `npx skillmds@latest add googlecloudplatform/scaffolding-api-routes`
- Raw SKILL.md: https://api.skillmd.com/api/skills/googlecloudplatform/scaffolding-api-routes/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Web & Frontend
- Author: GoogleCloudPlatform (https://skillmd.com/u/googlecloudplatform)
- Updated: 2026-09-17
- Page: https://skillmd.com/skills/googlecloudplatform/scaffolding-api-routes

---


# Scaffolding Modern API Routes

Translate legacy Express route definitions and middleware chains into modern **Next.js Route Handlers** with built-in validation and unified session management.

## Objective
Rebuild the documented API surface to ensure 1:1 functional parity with the legacy system, focusing on mapping **Express Middlewares** to **Next.js Route Guards**.

## Instructions for the Scaffold Subagent

Copy this checklist and track your progress:
```
Task Progress:
- [ ] Step 1: Analyze API Contracts
- [ ] Step 2: Establish Route Architecture
- [ ] Step 3: Map Middleware to Guards
- [ ] Step 4: Implement Zod-Backed Request Validation
- [ ] Step 5: Implement Resource Handlers
```

### Step 1. Analyze API Contracts
Locate and read `docs/legacy-audit/API_Contracts.md`. Identify:
- **Primary Routes & Sub-routes**: Map these to the Next.js App Router (e.g., `/api/[resource]/[sub-resource]/route.ts`).
- **Legacy Middleware Requirements**: Identify routes protected by Passport, custom "owner-only" checks, or roles.

### Step 2. Establish Route Architecture
Create the folder structure in `src/app/api/` representing the resources. Ensure that:
- **Dynamic Segments** (e.g., `[id]`) are used for resource-specific operations (GET single, PUT, DELETE).
- **Index Segments** (e.g., `/api/posts/route.ts`) are used for collection operations (GET list, POST new).

### Step 3. Map Middleware to Guards
Translate legacy Express middleware chains into **Modular Route Guards**:
- **Authentication**: Map `requiresLogin` to a `getServerSession(authOptions)` check.
- **Authorization (Ownership)**: Map `resourceAuth.hasAuthorization` to a "Resource Ownership Guard" (e.g., `if (resource.user_id !== session.user.id) throw Unauthorized`).
- **Authorization (Roles)**: Map role-specific middleware to logic that checks `session.user.role`.

### Step 4. Implement Zod-Backed Request Validation
For every incoming request (POST, PUT, PATCH):
- Use the **Zod Schemas** defined in `src/lib/models/schema.ts` (from Step 3) to validate `req.json()`.
- Ensure the API returns a standard `422 Unprocessable Entity` or `400 Bad Request` with a detailed error payload if validation fails.

### Step 5. Implement Resource Handlers
Write the `GET`, `POST`, `PUT`, `PATCH`, and `DELETE` functions.
- **Strict Response Envelopes**: Match the **Common Response Envelope** identified in the audit (e.g., whether to return a raw object or a wrapped `{ data: ... }`).
- **Pagination & Sorting**: Implement `skip`, `limit`, and `sort` parameters to mirror the legacy behavior precisely.
- **Status Code Parity**: Match the exact success and error status codes documented in `API_Contracts.md`.