---
name: Backend API Endpoint Generator
slug: backend-api-endpoint-generator
category: Automation
description: Backend API Endpoint Generator creates REST or GraphQL endpoints with validation, error handling, and tests. Use it when adding a new API route or endpoint to an existing codebase.
github: "https://github.com/alekspetrov/navigator/tree/main/skills/backend-endpoint"
language: Python
stars: 230
forks: 11
install: "npx degit https://github.com/alekspetrov/navigator/tree/main/skills/backend-endpoint ~/.claude/skills/backend-endpoint"
installs_to: ~/.claude/skills/backend-endpoint
source_path: skills/backend-endpoint/SKILL.md
collection_size: 25
category_size: 1754
collection_url: "https://dirskills.com/collections/alekspetrov/navigator"
added: 2026-09-03T06:04:38.041Z
last_synced: 2026-09-03T06:04:38.041Z
canonical_url: "https://dirskills.com/skills/backend-api-endpoint-generator"
---

# Backend API Endpoint Generator

Backend API Endpoint Generator creates REST or GraphQL endpoints with validation, error handling, and tests. Use it when adding a new API route or endpoint to an existing codebase.

**Install:**

```bash
npx degit https://github.com/alekspetrov/navigator/tree/main/skills/backend-endpoint ~/.claude/skills/backend-endpoint
```

## README

# 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.

```bash
PLUGIN_DIR="${CLAUDE_PLUGIN_ROOT:-$HOME/.claude/plugins/cache/navigator-marketplace/navigator}"
[ -d "$PLUGIN_DIR" ] || 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:
```bash
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`

```bash
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/validation_generator.py`

```bash
python3 functions/validation_generator.py \
  --resource "User" \
  --method "POST" \
  --fields "name:string:required,email:email:required,age:number:optional" \
  --library "zod" \
  --output "src/validators/user.validator.ts"
```

**Supported validation libraries**:
- Zod (default, TypeScript-first)
- Joi (JavaScript schema)
- Yup (object schema)
- Express-validator (middleware-based)

**Output example (Zod)**:
```typescript
import { z } from 'zod';

export const createUserSchema = z.object({
  name: z.string().min(1),
  email: z.string().email(),
  age: z.number().optional(),
});

export type CreateUserInput = z.infer<typeof createUserSchema>;
```

### Step 4: Generate Error Handling Middleware

**Write the error handler inline** (no generator script ships for this — author it directly to match the project's existing error-handling pattern).

Write to `src/middleware/errorHandler.ts` an error handler that includes:
- HTTP status code mapping
- Error response formatting
- Logging integration
- Development vs production modes
- Validation error handling

Follow the framework's idiom (Express error middleware `(err, req, res, next)`; Next.js route-level `try/catch` returning `NextResponse.json`).

### Step 5: Generate Test File

**Write the test inline**, using `templates/endpoint-test-template.spec.ts` as the reference shape (it ships as a reference template; no generator script drives it). Output to `tests/routes/users.test.ts`.

**The test should cover**:
- Success case (200/201)
- Validation errors (400)
- Not found (404)
- Unauthorized (401)
- Server errors (500)
- Edge cases

**Example test**:
```typescript
describe('GET /api/users/:id', () => {
  it('returns user when found', async () => {
    const response = await request(app)
      .get('/api/users/123')
      .expect(200);

    expect(response.body).toMatchObject({
      id: '123',
      name: expect.any(String),
    });
  });

  it('returns 404 when user not found', async () => {
    await request(app)
      .get('/api/users/999')
      .expect(404);
  });
});
```

### Step 6: Generate API Documentation Comment

**JSDoc or OpenAPI annotation**:

```typescript
/**
 * @route GET /api/users/:id
 * @description Get user by ID
 * @access Private
 * @param {string} id - User ID
 * @returns {User} User object
 * @throws {404} User not found
 * @throws {401} Unauthorized
 */
```

### Step 7: Show Endpoint Summary

**Display generated files and usage**:

```
✅ Endpoint Created: GET /api/users/:id

Structure:
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
📁 src/
   ├── routes/users.ts                (Route handler)
   ├── validators/user.validator.ts   (Request validation)
   └── middleware/errorHandler.ts     (Error handling)

📁 tests/
   └── routes/users.test.ts           (Integration tests)
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━

Route Registration:
import { userRoutes } from './routes/users';
app.use('/api', userRoutes);

Test:
curl http://localhost:3000/api/users/123
# or
npm test -- users.test.ts

Next Steps:
1. Implement business logic in controller
2. Connect to database/service layer
3. Run tests: npm test
4. Test with Postman/Thunder Client
```

### Step 8: Emit Execution Summary (Graph Ingestion)

After Step 7, emit an `execution_summary` JSON block. This is the parity equivalent of the `research_findings` block emitted by `navigator-research`, ingested into the knowledge graph so future endpoint work can surface what we learned.

**Output the block verbatim** (replace placeholders with actual values):

```json
{
  "execution_summary": {
    "skill": "backend-endpoint",
    "task": "{METHOD} {PATH}",
    "files_created": ["{route, validator, test paths}"],
    "files_modified": ["{router registration paths}"],
    "tests_added": ["{test file path}"],
    "stack_detected": "{e.g. express+typescript+zod}",
    "patterns_followed": [
      {"summary": "{convention applied — e.g. Zod schema for request validation}", "concepts": ["api"], "confidence": 0.8}
    ],
    "decisions_made": [
      {"summary": "{non-obvious choice — e.g. 404 over 422 because resource itself missing}", "concepts": ["api"], "confidence": 0.75, "evidence": "{path:line}"}
    ],
    "pitfalls_avoided": [
      {"summary": "{gotcha that future agents should know — e.g. middleware order matters: auth before validator}", "concepts": ["api"], "confidence": 0.85}
    ],
    "assumptions_made": ["{e.g. project uses Express middleware pattern (detected via package.json)}"]
  }
}
```

**Ingestion** (run from project root):

```bash
PLUGIN_DIR="${CLAUDE_PLUGIN_ROOT:-$HOME/.claude/plugins/cache/navigator-marketplace/navigator}"
[ -d "$PLUGIN_DIR" ] || PLUGIN_DIR="$HOME/.claude/plugins/marketplaces/navigator-marketplace"
echo '<execution_summary JSON>' | python3 "$PLUGIN_DIR/skills/nav-graph/functions/execution_to_graph.py" -
```

**Rules**:
- Only include non-obvious entries — empty/trivial blocks pollute the graph.
- Skip the entire block if there's nothing notable to record.
- Confidence ≥ 0.7 for first-hand execution; 0.75 is a reasonable default.

---

## Predefined Functions

### 1. route_validator.py

Validates route path follows REST conventions.

**Usage**:
```bash
python3 functions/route_validator.py --path "/api/users/:id" --method "GET"
```

**Checks**:
- RESTful naming (plural resources)
- Path parameter syntax (`:id` or `{id}`)
- No trailing slashes
- HTTP method matches intent

**Returns**: Valid path or error message

---

### 2. endpoint_generator.py

Generates endpoint handler from template.

**Usage**:
```bash
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"
```

**Parameters**:
- `--path`: API endpoint path
- `--method`: HTTP method
- `--resource`: Resource name (singular, PascalCase)
- `--framework`: Backend framework
- `--auth`: Include auth middleware
- `--validation`: Include validation middleware
- `--template`: Template file path

**Returns**: Generated endpoint code

---

### 3. validation_generator.py

Generates request validation schema.

**Usage**:
```bash
python3 functions/validation_generator.py \
  --resource "User" \
  --method "POST" \
  --fields "name:string:required,email:email:required" \
  --library "zod"
```

**Supported field types**:
- `string`, `number`, `boolean`
- `email`, `url`, `uuid`
- `array`, `object`
- `date`, `datetime`

**Returns**: Validation schema code

---

> **Error handling and tests are written inline** (Steps 4–5) — no
> `error_handler_generator.py` / `test_generator.py` ship with this skill.

---

## Templates

### express-route-template.ts

Express.js route handler template.

**Placeholders** (exactly those present in `templates/express-route-template.ts`):
- `${ROUTE_PATH}` - API endpoint path
- `${HTTP_METHOD}` - HTTP method (uppercase)
- `${HTTP_METHOD_LOWER}` - HTTP method (lowercase, for the router call)
- `${RESOURCE_NAME}` - Resource name (PascalCase)
- `${RESOURCE_NAME_LOWER}` - Resource name (lowercase)
- `${MIDDLEWARE_BLOCK}` - Auth + validation middleware chain (built by `endpoint_generator.py` from the `--auth`/`--validation` flags)

### nextjs-route-template.ts (collection)

Next.js App Router Route Handler for a **collection** endpoint — no dynamic segment.

**When to use**: `package.json` has `"next"` in deps **and** the path has no `[id]`. Output path: `app/api/<resource>/route.ts`. Exports `GET` (list) + `POST` (create).

### nextjs-route-dynamic-template.ts (single resource)

Next.js App Router Route Handler for a **single resource** endpoint with a dynamic segment.

**When to use**: path includes `[id]` (or similar). Output path: `app/api/<resource>/[id]/route.ts`. Exports `GET` (read), `PATCH` (update), `DELETE`.

**Picking between them**:
- `POST /api/favourites` → collection template
- `GET /api/favourites/[id]` → dynamic template
- If unsure, ask the user whether the endpoint operates on a list or a single resource

**Both templates encode Next.js 15+/16 conventions**:
- Named async exports per HTTP method
- `params` is a `Promise<…>` — `await` it (Next.js 15+ change), **only on dynamic**
- Non-dynamic routes do not declare a context parameter (TypeScript infers `Promise<{}>` from the file path)
- Returns `NextResponse.json(...)` with explicit status codes
- Zod schema for body validation
- See `.agent/philosophy/NEXTJS-PATTERNS.md` §E, §H

**Prefer Server Actions** over Route Handlers for **mutations from your own UI** (forms, buttons). Use Route Handlers for webhooks, third-party callers, and public REST endpoints. See `NEXTJS-PATTERNS.md` §F.

> Fastify, GraphQL, and Zod-schema generation are produced **inline** by the
> model / `validation_generator.py` (Zod is built via its `ZOD_TYPE_MAP`, no
> template file). Only the Express + Next.js route templates and the test
> template below ship on disk.

### endpoint-test-template.spec.ts

Integration test template with supertest (reference shape — written inline in Step 5).

**Placeholders**:
- `${ENDPOINT_PATH}` - Endpoint to test
- `${HTTP_METHOD}` - HTTP method
- `${TEST_CASES}` - Generated test cases

---

## Examples

See `examples/` directory for reference implementations:

1. **users-get.ts** - GET endpoint with auth
2. **users-post.ts** - POST endpoint with validation

Each example includes:
- Route/resolver implementation
- Validation schema
- Error handling
- Test file
- Usage documentation

---

## Best Practices

### REST API Design
- **Use plural nouns** for resources (`/users`, not `/user`)
- **Use HTTP methods correctly** (GET=read, POST=create, PUT/PATCH=update, DELETE=remove)
- **Nest resources properly** (`/users/:userId/posts/:postId`)
- **Return proper status codes** (200, 201, 400, 401, 404, 500)

### Request Validation
- **Validate all inputs** (body, params, query)
- **Fail fast** (validate before business logic)
- **Clear error messages** (tell user what's wrong)
- **Sanitize inputs** (prevent injection attacks)

### Error Handling
- **Centralized error handler** (DRY principle)
- **Consistent error format** (always same structure)
- **Don't expose internals** (sanitize stack traces in production)
- **Log errors** (for debugging)

### Security
- **Authentication** (verify identity)
- **Authorization** (check permissions)
- **Rate limiting** (prevent abuse)
- **Input sanitization** (prevent XSS, SQL injection)

### Testing
- **Test happy path** (success cases)
- **Test error cases** (validation, auth, not found)
- **Test edge cases** (empty data, large data)
- **Mock external dependencies** (database, APIs)

---

## Troubleshooting

### Route Not Found (404)

**Problem**: Endpoint returns 404 even though route is defined

**Solutions**:
1. Check route registration order (specific before generic)
2. Verify path matches exactly (case-sensitive)
3. Check middleware isn't blocking request
4. Validate HTTP method matches

### Validation Always Fails

**Problem**: Valid requests fail validation

**Solutions**:
1. Check field names match exactly
2. Verify data types are correct
3. Check required vs optional fields
4. Inspect validation error message

### Tests Failing

**Problem**: Integration tests don't pass

**Solutions**:
1. Ensure test database is seeded
2. Check test fixtures are correct
3. Verify mocks are set up properly
4. Run tests with `--verbose` flag

---

## Success Criteria

**This skill succeeds when**:
- [ ] Endpoint responds with correct status codes
- [ ] Request validation catches invalid inputs
- [ ] Error handling works consistently
- [ ] Tests cover success and error cases
- [ ] Code follows REST/GraphQL conventions
- [ ] Documentation is clear and complete

---

**Auto-invoke this skill when creating API endpoints to ensure consistency and security** 🔒