golang-api-design

Define RESTful and gRPC API design guidelines for resource naming, versioning, and validation.

Updated Aug 23, 2026

Search Tags:#design #versioning #api #validation #rest #pagination #grpc

Ready to run

npx skills add https://github.com/ep0ll/bons-ci --skill golang-api-design

💬 Prompt for ChatGPT / Claude Chat▼

Please help me install this Agent Skill.
Skill: golang-api-design
Source: https://github.com/ep0ll/bons-ci/tree/main/.agents/skills/api-design
Command: npx skills add https://github.com/ep0ll/bons-ci --skill golang-api-design

SYSTEM DOCUMENTATION & REQUIREMENTS

💡 This Skill includes references (resource) components.

What problem does it solve?

This Skill provides comprehensive guidelines for designing effective and maintainable API surfaces for HTTP and gRPC protocols.

Core Features & Use Cases

API Structuring: Defines resource naming, versioning, and endpoint conventions.
Standard Responses: Implements consistent request/response envelopes and error handling.
Validation & Parsing: Establishes best practices for request decoding, validation, and error responses.
Pagination & Conditional Requests: Incorporates cursor-based pagination and ETag mechanisms.
OpenAPI & Proto: Supports API definition through OpenAPI spec and gRPC protocol buffers.
Application: Useful for API designers, backend engineers, and teams building scalable, versioned APIs with best practices.

Quick Start

Use the guidelines to structure your API endpoints, validate requests, and implement versioned, secure, and scalable services.

Frequently Asked Questions about golang-api-design

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

FAQPage Schema

What are the best practices for RESTful API resource naming and versioning?▼

RESTful API resource naming and versioning best practices involve defining clear endpoint conventions for resource structures and implementing version control. This ensures maintainable API surfaces for HTTP protocols while standardizing request and response interactions.

How do I implement cursor-based pagination and ETag mechanisms for APIs?▼

Cursor-based pagination and ETag mechanisms are implemented by incorporating conditional request handling. This approach manages large datasets efficiently and supports client-side caching validation for scalable backend development.

What is the standard way to handle API validation and error responses?▼

API validation and error responses are standardized through consistent request decoding and defined response envelopes. Establishing these best practices ensures reliable parsing, structured validation feedback, and uniform error handling across HTTP and gRPC protocols.

Should I use OpenAPI spec or gRPC protocol buffers for API definition?▼

OpenAPI specs and gRPC protocol buffers serve API definition by structuring endpoint contracts. OpenAPI supports RESTful HTTP design, while protocol buffers define gRPC services, allowing teams to standardize scalable and versioned API surfaces effectively.

How does gRPC API design differ from RESTful API structuring?▼

gRPC API design differs from RESTful structuring by utilizing protocol buffers for service definitions rather than HTTP endpoint conventions. Both require standardized validation, pagination, and error handling to build scalable, versioned backend services.