# API Server

> Standards for building HTTP services, REST APIs, and middleware in Golang.

- Skill: `majiayu000/api-server` (Agent Skill, multi-file: 2 files)
- Install (CLI): `npx skillmds add majiayu000/api-server`
- Raw SKILL.md: https://api.skillmd.com/api/skills/majiayu000/api-server/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Integrations & APIs
- Author: majiayu000 (https://skillmd.com/u/majiayu000)
- Updated: 2026-09-09
- Page: https://skillmd.com/skills/majiayu000/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

- **Business Logic in Handlers**: Handlers should only parse request -> call service -> format response.
- **Global Router**: Don't use global router variables. Pass router instance.

## References

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