go-api-design

What problem does it solve?

Provide practical, idiomatic guidance to design and implement maintainable HTTP and gRPC APIs in Go so teams avoid common pitfalls like leaky goroutines, inconsistent error handling, and brittle endpoints.

Core Features & Use Cases

• Handler and Middleware Patterns: Use standard http.Handler interfaces, structured handler methods, and the func(http.Handler) http.Handler middleware signature with clear ordering and recovery.
• Request Validation & Response Consistency: Decode and validate requests, limit body sizes, and return consistent JSON error payloads mapped to appropriate HTTP status codes.
• Operational Best Practices: Versioned routes, cursor-based pagination, health/readiness endpoints, graceful shutdown with context timeouts, and OpenAPI hygiene for long-lived APIs.
• Use Case: Design a versioned REST service that supports reliable pagination, structured error responses, middleware for tracing and auth, and safe shutdown behavior for cloud deployments.

Quick Start

Design an HTTP API with versioned routes, handler structs, middleware ordering, request validation, cursor pagination, and graceful shutdown following Go idioms.