copilot-dev: Skill for Claude Code

API Endpoint Generator Skill

You are an expert API designer. When this skill activates, you generate complete, production-ready REST API endpoints for either TypeScript/Express or Python/FastAPI. Follow every step below exactly.

Step 1: Gather Requirements

Before generating any code, determine:

1. Framework: TypeScript + Express, or Python + FastAPI?
2. Resource: What entity is being managed? (e.g., User, Order, Product)
3. HTTP method and path: GET /users/:id, POST /products, etc.
4. Input shape: What fields does the request body, path params, or query params contain?
5. Output shape: What does a success response look like?
6. Business rules: Any constraints on the input? (e.g., email must be unique, age >= 18)

If any of these are missing from the user's prompt, ask for them before generating.

Step 2: Apply the Standard Output Structure

Every generated endpoint must include all five layers:

Layer	Purpose
Schema / Validator	Zod (TS) or Pydantic (Python) defines input shape and validates at the boundary
Route Handler	The async function that orchestrates validation, logic, and response
Typed Request/Response	TypeScript generics or Python type hints — no any, no dict without hints
Error Handling	RFC 7807 Problem Details format for all 4xx/5xx responses
Unit Test Stub	Vitest (TS) or pytest (Python) — all happy path + key error paths

Step 3: TypeScript / Express Pattern

Follow this exact template for TypeScript endpoints:

import { Router, Request, Response, NextFunction } from 'express';
import { z } from 'zod';

// --- 1. Input schema (validates and infers the TS type simultaneously) ---
const CreateUserSchema = z.object({
  email: z.string().email({ message: 'Must be a valid email address' }),
  name: z.string().min(2).max(100),
  age: z.number().int().min(0).max(150),
});

// Infer the TypeScript type from the schema — single source of truth
type CreateUserInput = z.infer<typeof CreateUserSchema>;

// --- 2. Response type ---
interface UserResponse {
  id: string;
  email: string;
  name: string;
  createdAt: string;
}

// --- 3. Route handler ---
/**
 * POST /users
 *
 * Creates a new user account.
 *
 * @param req.body - {@link CreateUserInput}
 * @returns 201 with the created {@link UserResponse}
 * @throws 400 if the request body fails validation
 * @throws 409 if the email address is already registered
 */
async function createUser(
  req: Request,
  res: Response<UserResponse>,
  next: NextFunction,
): Promise<void> {
  // Validate input — parse() throws ZodError on failure
  const parseResult = CreateUserSchema.safeParse(req.body);

  if (!parseResult.success) {
    // RFC 7807 Problem Details — consistent error envelope
    res.status(400).json({
      type: 'https://errors.myapp.com/validation-error',
      title: 'Validation Error',
      status: 400,
      detail: 'One or more fields failed validation.',
      errors: parseResult.error.flatten().fieldErrors,
    } as any);
    return;
  }

  // parseResult.data is now fully typed as CreateUserInput
  const input: CreateUserInput = parseResult.data;

  try {
    // Replace with your actual service/repository call
    const user = await userService.create(input);

    // Return immutable response — never mutate the entity object directly
    res.status(201).json({
      id: user.id,
      email: user.email,
      name: user.name,
      createdAt: user.createdAt.toISOString(),
    });
  } catch (error) {
    // Delegate unexpected errors to Express error middleware
    next(error);
  }
}

// --- 4. Router registration ---
export const userRouter = Router();
userRouter.post('/', createUser);