Implement Backend Routing and Controllers

Purpose

Provide a repeatable way to define HTTP routes and implement controllers that validate input, call services, and return consistent responses.

When to use

Use this skill when you are:

• Adding a new endpoint (GET/POST/PUT/PATCH/DELETE)
• Refactoring endpoints with “fat routes”
• Standardizing controller error handling and response shapes
• Introducing request validation at the HTTP boundary

Inputs

• Endpoint contract: method, path, authentication/authorization requirements
• Request input shapes (params/query/body)
• Response shape (success and failure)
• Service function(s) the controller will call

Outputs

• Route registration that wires middleware and delegates to controller methods
• Controller methods with:
  • input validation
  • service calls
  • consistent success responses
  • consistent error mapping

Required rules

• Routes MUST NOT contain business logic.
• Controllers MUST NOT contain persistence queries (unless the codebase intentionally collapses layers).
• Controllers MUST validate untrusted inputs (params/query/body).
• Controllers MUST map errors to consistent HTTP responses.

Controller responsibilities

A controller SHOULD:

• Validate and normalize inputs
• Translate service results into a response DTO
• Choose the appropriate status code (200, 201, 204, etc.)
• Map operational errors to 4xx / 5xx consistently

A controller SHOULD NOT:

• Implement business rules (belongs in services)
• Contain database queries (belongs in repositories)

Route responsibilities

A route SHOULD:

• Register middleware in the correct order
• Delegate to a controller method
• Avoid inline logic beyond trivial parameter passing

Steps

1. Define the endpoint contract (method, path, auth, request/response).
2. Add route registration:
   • register middleware
   • delegate to controller method
3. Implement controller method:
   • validate inputs
   • call service
   • return a consistent response
4. Add or update validation schemas.
5. Verify behavior with:
   • one happy-path call
   • one validation failure
   • one auth/permission failure (if applicable)

Verification

• Route handler is short and delegates immediately
• Controller validates all external inputs
• Response payload matches the documented shape
• Errors map to consistent 4xx/5xx with stable error codes
• Happy-path request returns expected status and response
• Validation failure returns structured error

Boundaries

• MUST NOT embed business logic in routes
• MUST NOT embed persistence queries in controllers
• MUST NOT skip input validation for external data
• MUST NOT return inconsistent error shapes across endpoints
• SHOULD NOT create fat controllers (keep them thin, delegate to services)
• SHOULD NOT bypass error mapping middleware

Included assets

• Templates: ./templates/ provides router and controller scaffolds.
• Examples: ./examples/ includes a complete controller, route file, and refactoring walkthrough.