API Design

Design REST APIs with URL structures, response formats, and error handling.

1|3|Updated Feb 17, 2026

Search Tags:#versioning #documentation #openapi #rest #graphql #rubrics #api-design

Ready to run

npx skills add https://github.com/yogi100x/acceleration-council --skill api-design-yogi100x

💬 Prompt for ChatGPT / Claude Chat▼

Please help me install this Agent Skill.
Skill: API Design
Source: https://github.com/yogi100x/acceleration-council/tree/main/tech/api-design
Command: npx skills add https://github.com/yogi100x/acceleration-council --skill api-design-yogi100x

SYSTEM DOCUMENTATION & REQUIREMENTS

What problem does it solve?

API design helps teams build scalable, consistent, and well-documented interfaces that other services and clients can reliably consume, reducing integration friction and maintenance costs.

Core Features & Use Cases

REST design principles with clear URL structures and stable versioning.
Comprehensive documentation, OpenAPI specs, and standardized error handling.
Versioning strategies, anti-pattern avoidance, and a robust quality rubric for API surfaces.

Quick Start

Define a standard API surface using REST + OpenAPI conventions and wire up a minimal resource endpoint to validate the design.

Frequently Asked Questions about API Design

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

FAQPage Schema

How do I design consistent REST APIs with clear URL structures and stable versioning?▼

To design consistent REST APIs, define clear URL structures, standard response formats, and robust error handling. Implement stable versioning strategies to ensure external developers and mobile clients can reliably consume your services without integration friction.

When should I choose GraphQL, gRPC, or WebSockets over REST for my API architecture?▼

Choose GraphQL, gRPC, or WebSockets over REST when your architecture demands specific communication patterns. Select GraphQL for flexible data queries, gRPC for high-performance internal microservices, and WebSockets for real-time features, applying REST for standard resource-based interfaces.

What's the best way to document API surfaces and avoid common anti-patterns?▼

The best way to document API surfaces is generating comprehensive OpenAPI specifications alongside your REST endpoints. Applying a structured quality rubric helps avoid common anti-patterns, ensuring your interface remains scalable, consistent, and easy for consumers to integrate.

How does pagination and authentication factor into robust API design?▼

Pagination and authentication are core requirements for robust API design. Implement standardized pagination to manage large datasets efficiently and enforce secure authentication protocols to protect internal services and external developers consuming your endpoints.

Can I use this approach to standardize error handling across microservices?▼

Yes, you can standardize error handling across microservices by applying a consistent API design rubric. Defining uniform response formats and error handling rules reduces maintenance costs and ensures all clients receive predictable failure states across the architecture.