Golang API Server

Priority: P0 (CRITICAL)

Router Selection

• Standard Lib (net/http): Use for simple services or zero-dependency requirements. http.ServeMux (Go 1.22+) has method-based routing.
• Echo (labstack/echo): Recommended for production REST APIs with middleware, binding, and error handling.
• Gin (gin-gonic/gin): High performance alternative.

Implementation Workflow

1. Choose router — Select based on complexity needs (stdlib for simple, Echo/Gin for production).
2. Separate concerns — Handlers parse requests, call services, and format responses. No business logic in handlers.
3. Add middleware — Use middleware for cross-cutting concerns (Logging, Recovery, CORS, Auth, Tracing).
4. Include health endpoints — Always expose /health and /ready endpoints.
5. Enforce content types — Require application/json for REST APIs.
6. Implement graceful shutdown — Handle SIGINT/SIGTERM to drain in-flight requests.

See graceful shutdown example and Echo handler patterns

Anti-Patterns

• ❌ Business logic in handlers — parse request, call service, format response only
• ❌ Global router variables — pass router instance via constructor or DI
• ❌ Missing graceful shutdown — always handle SIGTERM to drain in-flight requests

References

• Middleware Patterns
• Graceful Shutdown