Add API Skill

You are a backend API expert. When this skill is invoked, create a new API endpoint with proper validation, error handling, and tests.

What This Skill Does

Generates a complete API endpoint including route handler, input validation, business logic, error handling, and test coverage.

Step-by-Step Instructions

1. Understand the endpoint requirements. Clarify:

   • HTTP method and path (e.g., POST /api/projects)
   • What the endpoint does
   • Request body or query parameter schema
   • Response format
   • Authentication requirements
   • Authorization rules (who can access this)

2. Study existing API patterns. Before writing code, examine:

   • How other endpoints are structured in the project
   • The validation library in use (Zod, Joi, Yup, class-validator, etc.)
   • Error handling patterns and error response format
   • Middleware chain (auth, logging, rate limiting)
   • Database access patterns (ORM, query builder, raw SQL)
   • Response formatting conventions

3. Define the types. Create TypeScript interfaces or types for:

   • Request body (if POST/PUT/PATCH)
   • Query parameters (if GET with filters)
   • Path parameters
   • Response body (success case)
   • Error response body

4. Create the validation schema. Using the project’s validation library:

   • Validate all input fields with appropriate rules
   • Add custom error messages for each field
   • Handle optional vs required fields
   • Validate nested objects and arrays
   • Add format validation (email, URL, UUID, etc.)

5. Implement the route handler:

   • Parse and validate input
   • Check authentication and authorization
   • Execute business logic (ideally in a separate service layer)
   • Handle errors with appropriate HTTP status codes
   • Return a consistent response format
   • Add logging for important operations

6. Implement error handling. Use proper HTTP status codes:

   • 400 - Invalid input (validation errors)
   • 401 - Not authenticated
   • 403 - Not authorized
   • 404 - Resource not found
   • 409 - Conflict (duplicate resource)
   • 422 - Unprocessable entity
   • 429 - Rate limited
   • 500 - Internal server error (catch-all)

7. Write tests. Create tests covering:

   • Happy path: valid request returns correct response
   • Validation: invalid inputs return 400 with field-level errors
   • Authentication: unauthenticated requests return 401
   • Authorization: unauthorized requests return 403
   • Not found: missing resources return 404
   • Edge cases: empty body, extra fields, boundary values

8. Register the route. Add the endpoint to the router or route configuration.

9. Run all tests and linting. Verify everything passes.

Guidelines

• Follow the project’s existing API patterns exactly. Consistency over novelty.
• Always validate input. Never trust client data.
• Keep the handler thin. Business logic belongs in a service layer.
• Return consistent error formats across all endpoints.
• Use appropriate HTTP methods (GET for reads, POST for creates, etc.).
• Do not expose internal errors to clients. Log them, return generic messages.
• Add rate limiting for public endpoints.
• If the endpoint modifies data, consider idempotency.
• Document the endpoint with JSDoc or equivalent.
• Keep files under 600 lines of code. Split large handlers into service + handler.