create-handler

Skill: Create API Handler

Step-by-step workflow for creating a new API handler following the {{CONFIG.patterns.handlerFlowSteps}}-step handler pattern.

Scripts (Cursor skills scripts/ support)

This skill includes a scripts/ folder. The agent can run these scripts as part of the workflow:

• scripts/scaffold-handler-dirs.sh — Creates the handler directory structure. Usage: ./scripts/scaffold-handler-dirs.sh <entity> <operation> (e.g. order create).

Trigger

When the user asks to create a new API endpoint, handler, or route.

Prerequisites

• Project configuration loaded ({{CONFIG.paths.handlerBasePath}} exists)
• Understanding of the entity and operation

Steps

Step 1: Gather Requirements

• Identify the entity (e.g., Order, Product, User)
• Identify the operation (e.g., create, read, update, list, delete)
• Determine HTTP method and URL path
• Identify request parameters and body schema
• Identify response format

Step 2: Create Directory Structure

mkdir -p {{CONFIG.paths.handlerBasePath}}/{entity}/{operation}/logic
mkdir -p {{CONFIG.paths.handlerBasePath}}/{entity}/{operation}/schemas

Expected structure:

{{CONFIG.paths.handlerBasePath}}/{entity}/{operation}/
├── {{CONFIG.fileNames.handlerEntry}}
├── logic/
│   ├── validate-request.ts
│   ├── validate-business.ts
│   ├── pre-processing.ts
│   ├── operation.ts
│   ├── post-operation.ts
│   └── response.ts
└── schemas/
    ├── {{CONFIG.fileNames.requestSchema}}
    └── {{CONFIG.fileNames.responseSchema}}

Step 3: Create Request Schema

• Define JSON Schema in schemas/{{CONFIG.fileNames.requestSchema}}
• Include all required and optional fields
• Add type validation and constraints
• Add description for each field

Step 4: Create Response Schema

• Define JSON Schema in schemas/{{CONFIG.fileNames.responseSchema}}
• Follow response envelope pattern: { data, meta }
• Include all response fields with types