# Golang API Server

> Standards for building HTTP services, REST APIs, and middleware in Golang. Use when building Go HTTP servers, REST APIs, or custom middleware. (triggers: cmd/server/*.go, internal/adapter/handler/**, http server, rest api, gin, echo, middleware)

- Skill: `comeonoliver/golang-api-server` (Agent Skill)
- Install (CLI): `npx skillmds@latest add comeonoliver/golang-api-server`
- Raw SKILL.md: https://api.skillmd.com/api/skills/comeonoliver/golang-api-server/raw
- Safety review: pending (external: skill-scanner PASS, skillspector PASS)
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: AI & ML
- Author: ComeOnOliver (https://skillmd.com/u/comeonoliver)
- Updated: 2026-09-08
- Page: https://skillmd.com/skills/comeonoliver/golang-api-server

---


# Golang API Server Standards

## **Priority: P0 (CRITICAL)**

## Router Selection

- **Standard Lib (`net/http`)**: Use for simple services or when zero deps is required. Use `http.ServeMux` (Go 1.22+ has decent routing).
- **Echo (`labstack/echo`)**: Recommended for production REST APIs. Excellent middleware support, binding, and error handling.
- **Gin (`gin-gonic/gin`)**: High performance alternative.

## Guidelines

- **Graceful Shutdown**: MUST implement graceful shutdown to handle in-flight requests on termination (SIGINT/SIGTERM).
- **DTOs**: Separate Domain structs from API Request/Response structs. Map between them.
- **Middleware**: Use middleware for cross-cutting concerns (Logging, Recovery, CORS, Auth, Tracing).
- **Health Checks**: Always include `/health` and `/ready` endpoints.
- **Content-Type**: Enforce `application/json` for REST APIs.

## Middleware Pattern

- Standard: `func(next http.Handler) http.Handler`
- Echo implementation: `func(next echo.HandlerFunc) echo.HandlerFunc`

## Anti-Patterns

- **No business logic in handlers**: Parse request → call service → format response only.
- **No global router vars**: Pass router instance via constructor or DI.
- **No missing graceful shutdown**: Always handle SIGTERM to drain in-flight requests.

## References

- [Middleware Patterns](references/middleware-patterns.md)
- [Graceful Shutdown](references/graceful-shutdown.md)