gh-alekspetrov-navigator/skills/backend-endpoint/SKILL.md

---
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: 1.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 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
  - 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 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

**Use predefined function**: `functions/error_handler_generator.py`

```bash
python3 functions/error_handler_generator.py \
  --framework "express" \
  --template "templates/error-handler-template.ts" \
  --output "src/middleware/errorHandler.ts"
```

**Error handler includes**:
- HTTP status code mapping
- Error response formatting
- Logging integration
- Development vs production modes
- Validation error handling

### Step 5: Generate Test File

**Use predefined function**: `functions/test_generator.py`

```bash
python3 functions/test_generator.py \
  --endpoint "/api/users/:id" \
  --method "GET" \
  --framework "express" \
  --template "templates/endpoint-test-template.spec.ts" \
  --output "tests/routes/users.test.ts"
```

**Test template includes**:
- 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
```

---

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

---

### 4. error_handler_generator.py

Generates error handling middleware.

**Usage**:
```bash
python3 functions/error_handler_generator.py \
  --framework "express" \
  --template "templates/error-handler-template.ts"
```

**Returns**: Error handler middleware code

---

### 5. test_generator.py

Generates endpoint integration tests.

**Usage**:
```bash
python3 functions/test_generator.py \
  --endpoint "/api/users/:id" \
  --method "GET" \
  --framework "express" \
  --template "templates/endpoint-test-template.spec.ts"
```

**Generates tests for**:
- Success responses
- Validation errors
- Authentication errors
- Not found errors
- Server errors

**Returns**: Generated test code

---

## Templates

### express-route-template.ts

Express.js route handler template.

**Placeholders**:
- `${ROUTE_PATH}` - API endpoint path
- `${HTTP_METHOD}` - HTTP method (lowercase)
- `${RESOURCE_NAME}` - Resource name (PascalCase)
- `${VALIDATION_MIDDLEWARE}` - Validation middleware
- `${AUTH_MIDDLEWARE}` - Authentication middleware

### fastify-route-template.ts

Fastify route handler template (alternative).

### graphql-resolver-template.ts

GraphQL resolver template (alternative).

### validation-zod-template.ts

Zod validation schema template.

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

Integration test template with supertest.

**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
3. **graphql-resolver.ts** - GraphQL mutation example

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** 🔒