@incidental/project-templates/templates/skills/api-generator/SKILL.md

Claude Code template library for JavaScript projects with framework auto-detection

---
name: api-generator
description: Generate RESTful API endpoints with proper validation, error handling, and documentation
allowed-tools: Read, Write, Edit, Grep, Glob
---

# API Generator Skill

Generate complete RESTful API endpoints with best practices.

## When to Use

Use this skill when you need to:
- Create new API endpoints
- Build CRUD operations
- Add validation and error handling
- Generate API documentation
- Implement API authentication

## What This Skill Does

This skill generates production-ready API endpoints including:

1. **Route handlers** with proper HTTP methods (GET, POST, PUT, DELETE, PATCH)
2. **Request validation** using schema validation libraries
3. **Error handling** with appropriate status codes and messages
4. **Response formatting** with consistent JSON structure
5. **Authentication/Authorization** middleware
6. **Documentation** with JSDoc or OpenAPI/Swagger

## API Endpoint Template

For each endpoint, this skill creates:

### Request Validation
```javascript
// Using Zod or Joi for validation
const schema = z.object({
  name: z.string().min(1),
  email: z.string().email(),
  age: z.number().positive()
})
```

### Route Handler
```javascript
export async function POST(request) {
  try {
    // Validate request body
    const body = await request.json()
    const validated = schema.parse(body)

    // Business logic
    const result = await createUser(validated)

    // Success response
    return Response.json(
      { success: true, data: result },
      { status: 201 }
    )
  } catch (error) {
    // Error handling
    if (error instanceof ZodError) {
      return Response.json(
        { success: false, error: 'Validation failed', details: error.errors },
        { status: 400 }
      )
    }

    return Response.json(
      { success: false, error: 'Internal server error' },
      { status: 500 }
    )
  }
}
```

### Documentation
```javascript
/**
 * Create a new user
 *
 * @route POST /api/users
 * @param {Object} request.body - User data
 * @param {string} request.body.name - User's full name
 * @param {string} request.body.email - User's email address
 * @param {number} request.body.age - User's age
 * @returns {Object} 201 - User created successfully
 * @returns {Object} 400 - Validation error
 * @returns {Object} 500 - Internal server error
 */
```

## Response Format

All API responses follow this structure:

```javascript
// Success
{
  "success": true,
  "data": { /* response data */ }
}

// Error
{
  "success": false,
  "error": "Error message",
  "details": { /* error details */ }
}
```

## HTTP Status Codes

- **200** OK - Successful GET, PUT, PATCH
- **201** Created - Successful POST
- **204** No Content - Successful DELETE
- **400** Bad Request - Validation error
- **401** Unauthorized - Authentication required
- **403** Forbidden - Insufficient permissions
- **404** Not Found - Resource not found
- **500** Internal Server Error - Server error

## Security Considerations

- Validate all input data
- Sanitize user input to prevent injection
- Implement rate limiting
- Use authentication middleware
- Apply authorization checks
- Don't expose sensitive data in errors
- Use HTTPS in production
- Implement CORS properly