home / skills / hoangnguyen0403 / agent-skills-standard / api-server

api-server skill

This skill helps you implement Golang HTTP services following standard routing, middleware, health checks, and graceful shutdown for robust APIs.

npx playbooks add skill hoangnguyen0403/agent-skills-standard --skill api-server

Review the files below or copy the command above to add this skill to your agents.

Files (3)

SKILL.md

1.6 KB

---
name: API Server
description: Standards for building HTTP services, REST APIs, and middleware in Golang.
metadata:
  labels: [golang, http, api, rest, middleware]
  triggers:
    files: ['cmd/server/*.go', 'internal/adapter/handler/**']
    keywords: [http server, rest api, gin, echo, middleware]
---

# 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)

Overview

This skill defines standards for building HTTP services, REST APIs, and middleware in Golang. It focuses on practical choices for routers, mandatory operational patterns like graceful shutdown and health checks, and clear separation between API DTOs and domain models. The guidance emphasizes middleware use, content-type enforcement, and avoiding common anti-patterns. It is aimed at teams building reliable, maintainable Go APIs.

How this skill works

The skill inspects design and implementation choices against a concise checklist: router selection, middleware shape, DTO separation, health endpoints, graceful shutdown, and content-type handling. It checks for use of middleware patterns, verifies presence of /health and /ready endpoints, and flags business logic embedded in handlers or use of global router variables. It reports mismatches and recommends concrete changes aligned with best practices for production REST APIs.

When to use it

When starting a new Golang HTTP/REST service or refactoring an existing one
When choosing a router for production (std lib, Echo, or Gin guidance)
When onboarding engineers to consistent API and middleware patterns
Before deployment to ensure graceful shutdown and health/readiness endpoints are present
When auditing code for anti-patterns like business logic in handlers or global router use

Best practices

Prefer standard library for minimal services; use Echo for production REST APIs and Gin for high-performance needs
Implement graceful shutdown handling SIGINT/SIGTERM to drain in-flight requests
Keep API Request/Response DTOs separate from domain structs and map between them
Use middleware for logging, recovery, CORS, auth, and tracing; follow func(next http.Handler) http.Handler signature (or echo.HandlerFunc)
Expose /health and /ready endpoints and enforce application/json for REST responses
Avoid global router variables and keep handlers thin: parse → call service → format response

Example use cases

New microservice where you must pick a router and standardize middleware and error handling
Refactor an existing API to extract business logic from handlers into services and DTOs
Pre-deployment checklist to ensure graceful shutdown and readiness probes are implemented
Code review automation that flags missing health endpoints, incorrect content-type handling, or global router usage
Creating onboarding docs that explain middleware pattern and folder structure for handlers, services, and DTOs

FAQ

Which router should I pick for a production REST API?

Echo is recommended for production REST APIs due to its middleware, binding, and error handling; Gin is a good high-performance alternative; use net/http for simple or zero-dependency services.

How should I structure handlers and business logic?

Handlers should parse requests, call service layer functions, and format responses. Move business rules into services and keep DTOs separate from domain models.