/backend-endpoint

name: backend-endpoint
description: Create REST/GraphQL API endpoint with validation, error handling, and tests. Auto-invoke when user says "add endpoint", "create API", "new route", or "add route".
allowed-tools: Read, Write, Edit, Grep, Glob, Bash
version: 2.0.0

Backend API Endpoint Generator

Generate production-ready REST or GraphQL endpoints with request validation, error handling, and comprehensive tests.

When to Invoke

Auto-invoke when user mentions:

• "Add endpoint"
• "Create API"
• "New route"
• "Add route"
• "Create API endpoint for [resource]"

What This Does

1. Generates route handler with proper HTTP methods 2. Adds request validation (body, params, query) 3. Implements error handling 4. Creates test file with request/response tests 5. Follows REST/GraphQL conventions 6. Includes authentication middleware (if needed)

Execution Steps

Step 0: Check Existing Patterns (Phase 0)

Before gathering requirements, query the knowledge graph for what we already know about API/endpoint work in this project. Mirrors `navigator-research`'s Phase 0.

PLUGIN_DIR="${CLAUDE_PLUGIN_ROOT:-$(cat "${NAVIGATOR_CONFIG_HOME:-${XDG_CONFIG_HOME:-$HOME/.config}/navigator}/plugin-root" 2>/dev/null)}"
[ -d "$PLUGIN_DIR/skills" ] || PLUGIN_DIR="$HOME/.claude/plugins/marketplaces/navigator-marketplace"
python3 "$PLUGIN_DIR/skills/nav-graph/functions/graph_manager.py" \
  --action query --concept api \
  --graph-path .agent/knowledge/graph.json 2>/dev/null | head -40

Also check `authentication`, `validation`, and `security` if the endpoint touches those areas.

If memories surface (`PATTERN`, `PITFALL`, `DECISION` entries), read the full memory files for relevant ones:

ls .agent/knowledge/memories/{patterns,pitfalls,decisions}/ 2>/dev/null

**What to do with what you find**:

• **Patterns**: apply them (e.g. "we use Zod for validation, not Joi")
• **Pitfalls**: avoid them (record in `pitfalls_avoided` in Step 8)
• **Decisions**: respect them (e.g. "we return 404 over 422 for missing resources")

If the graph returns nothing useful, proceed without it. Skip this step only if the knowledge graph is disabled in `.agent/.nav-config.json`.

Step 1: Gather Endpoint Requirements

**Ask user for endpoint details**:

Endpoint path: [e.g., /api/users/:id]
HTTP method: [GET, POST, PUT, PATCH, DELETE]
Resource name: [e.g., User, Post, Product]

Framework:
  - express (default)
  - fastify
  - nestjs
  - nextjs   (App Router Route Handler — app/api/<resource>/route.ts)
  - graphql

Authentication required: [yes/no]
Request validation needed: [yes/no]

**Validate endpoint path**:

• Use predefined function: `functions/route_validator.py`
• Ensure RESTful conventions
• Check path parameters syntax
• No trailing slashes

Step 1.5: Verify Understanding (ToM Checkpoint) [EXECUTE]

**IMPORTANT**: This step MUST be executed for high-stakes operations.

**Before generating code, confirm interpretation with user**.

**Display verification**:

I understood you want:
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
Endpoint: {METHOD} {PATH}
Resource: {RESOURCE_NAME}
Framework: {FRAMEWORK} (detected from package.json / specified)
Auth required: {yes/no}
Validation needed: {yes/no}
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━

Assumptions I'm making:
- Using {VALIDATION_LIBRARY} for validation (detected from existing validators)
- Error handling follows existing pattern in {ERROR_HANDLER_PATH}
- Route will be registered at {ROUTE_PREFIX} prefix

Proceed with generation? [Y/n]

**Skip verification if** (HIGH-STAKES ONLY mode):

• Simple CRUD operation (single resource, single path parameter)
• User explicitly said "quick", "just do it", or "skip confirmation"
• No custom authentication logic specified
• Standard GET/POST/PUT/DELETE without complex business logic

**Always verify if**:

• Multiple path parameters (e.g., `/users/:userId/posts/:postId`)
• Custom authorization logic specified
• Non-standard HTTP methods or patterns
• GraphQL mutations with side effects
• Endpoints involving financial or sensitive data

Step 1.8: Declare Belief State (Optional - ToM Anchor)

**Before generating code, optionally declare explicit assumptions** (enabled by `tom_features.belief_anchors` in config).

**Display belief state anchor**:

📌 BELIEF STATE
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━

What I know (from context):
✅ Framework: {FRAMEWORK} (from package.json)
✅ TypeScript: {strict/normal} mode (from tsconfig.json)
✅ Validation: {LIBRARY} (from existing validators/)

What I'm assuming (inference):
🔸 Error handler follows pattern in {PATH}
🔸 Routes registered at {PREFIX} prefix
🔸 Using {CONVENTION} commit messages

What I don't know (using defaults):
❓ Request logging preference (will include)
❓ Rate limiting requirements (will skip)
❓ Response envelope format (will use standard)
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━

Adjustments needed before I proceed?

**Skip belief anchor if**:

• `tom_features.belief_anchors` is false in config
• User said "skip", "just do it", "quick"
• Simple endpoint with no custom logic

**Show belief anchor if**:

• Complex endpoint with multiple integrations
• User profile indicates preference for detailed explanations
• First endpoint in a new project (establishing patterns)

Step 2: Generate Route Handler

**Based on HTTP method and framework**:

Use predefined function: `functions/endpoint_generator.py`

python3 functions/endpoint_generator.py \
  --path "/api/users/:id" \
  --method "GET" \
  --resource "User" \
  --framework "express" \
  --auth true \
  --validation true \
  --template "templates/express-route-template.ts" \
  --output "src/routes/users.ts"

**Template includes**:

• Route definition
• Request validation middleware
• Controller/handler function
• Error handling
• Response formatting
• TypeScript types

Step 3: Generate Validation Schema

**Use predefined function**: `functions/val