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

Step 5: Implement Logic Steps

For each file in logic/:

• [ ] validate-request.ts — Validate request against schema
• [ ] validate-business.ts — Check business rules and entity state
• [ ] pre-processing.ts — Transform and enrich data
• [ ] operation.ts — Execute core business logic
• [ ] post-operation.ts — Trigger side effects (events, notifications)
• [ ] response.ts — Format response with envelope

Step 6: Create Handler Entry Point

• [ ] Import all logic steps
• [ ] Wire up the {{CONFIG.patterns.handlerFlowSteps}}-step flow
• [ ] Add error handling with try/catch
• [ ] Add structured logging with correlationId
• [ ] Export handler function

Step 7: Register Route

• [ ] Add route in the appropriate router file
• [ ] Apply authentication middleware
• [ ] Apply rate limiting if needed

Step 8: Add Tests

• [ ] Create test file: {entity}/{operation}/__tests__/handler.test.ts
• [ ] Test each logic step independently
• [ ] Test handler integration (success path)
• [ ] Test error cases (validation, business, not found)
• [ ] Verify {{CONFIG.testing.coverageMinimum}}% coverage

Step 9: Validate

• [ ] Run type check: {{CONFIG.testing.typeCheckCommand}}
• [ ] Run tests for the new handler only
• [ ] Verify schemas match implementation

Completion

Handler is created, tested, and type-checked. Ready for code review.

If a step fails

• Step 2 (directory): Ensure {{CONFIG.paths.handlerBasePath}} exists. Run mkdir -p from project root.
• Step 3–4 (schemas): If schema validation fails, check JSON Schema syntax. Use a minimal schema first.
• Step 5 (logic): If imports fail, verify paths match {{CONFIG.paths.commonPath}} and handler structure.
• Step 8 (tests): If tests fail, run {{CONFIG.testing.typeCheckCommand}} first. Fix type errors before test logic.
• Step 9 (validate): If type-check fails, fix reported errors before proceeding. Do not skip validation.