skills.rest
eduardo-sl
eduardo-slCOMMUNITY
Explore all skills by this author →
𝕏@spinelli_eduGitHub

go-api-design

Designs REST and gRPC APIs for Go with handlers, middleware, pagination, and graceful shutdown.

64|9|Updated Mar 27, 2026
Search Tags:#middleware#rest#go#http#grpc#api-design#graceful-shutdown
One-click install
npx skills add https://github.com/eduardo-sl/go-agent-skills --skill go-api-design
Or copy as Structured Prompt for Agent▼
Please help me install this Agent Skill.
Skill: go-api-design
Source: https://github.com/eduardo-sl/go-agent-skills/tree/main/skills/%28architecture%29/go-api-design
Command: npx skills add https://github.com/eduardo-sl/go-agent-skills --skill go-api-design

SYSTEM DOCUMENTATION & REQUIREMENTS

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.

Frequently Asked Questions about go-api-design

High-intent search queries and answers about installing and using this skill.

FAQPage Schema
How do I design a REST API in Go with standard http.Handler patterns and middleware?▼

Designing a REST API in Go with standard http.Handler patterns involves using structured handler methods and the func(http.Handler) http.Handler middleware signature to manage routing, tracing, and auth while ensuring consistent JSON error responses.

What is the best way to implement graceful shutdown and context propagation in a Go HTTP service?▼

Implementing graceful shutdown in a Go HTTP service requires propagating context timeouts to safely terminate in-flight requests, preventing leaky goroutines and ensuring cloud deployments handle termination signals without dropping active connections.

How does cursor-based pagination work for Go APIs and when should I use it?▼

Cursor-based pagination in Go APIs uses a pointer to the next result set rather than offsets, ensuring stable performance and consistency for long-lived APIs even when underlying data changes during pagination requests.

Can I use this approach to build both REST and gRPC services for microservices?▼

Yes, this approach supports building both REST and gRPC services in Go for microservices, providing idiomatic guidance for HTTP handlers, routing, versioning, and operational best practices like health and readiness endpoints.

How do I ensure consistent JSON error responses and request validation in Go backend services?▼

Consistent JSON error responses and request validation in Go backend services are achieved by decoding and validating requests, limiting body sizes, and mapping validation failures to appropriate HTTP status codes within structured handler logic.

Why does my Go API have leaky goroutines and brittle endpoints, and how can I fix it?▼

Leaky goroutines and brittle endpoints in Go APIs often result from improper context propagation and lack of graceful shutdown; fixing them requires standard http.Handler patterns, middleware recovery, and context timeouts.

Related Skills

Explore More Software Engineering Skills→
IntegralistIntegralist
2

go-api

Generate a complete Go API service project with templates and observability tools.

Community
Advanced
333-333-333333-333-333

go-api-docs

Generate OpenAPI specifications from Go swaggo annotations.

Community
Intermediate
jagreehaljagreehal
7

autotel-vitest

Create parent spans for each Vitest test with OpenTelemetry tracing.

Community
Intermediate
bobmatnycbobmatnyc
68

golang-grpc

Develop gRPC services in Go using versioned Protocol Buffers and TLS.

Community
Advanced