api-design

Design consistent APIs with versioning, pagination, error handling, and documentation.

Updated Feb 22, 2026
One-click install
npx skills add https://github.com/ps-carvalho/cortex-agents --skill api-design-ps-carvalho
Or copy as Structured Prompt for Agent
Please help me install this Agent Skill.
Skill: api-design
Source: https://github.com/ps-carvalho/cortex-agents/tree/main/.opencode/skills/api-design
Command: npx skills add https://github.com/ps-carvalho/cortex-agents --skill api-design-ps-carvalho

SYSTEM DOCUMENTATION & REQUIREMENTS

What problem does it solve?

REST, GraphQL, gRPC and WebSocket API design often lacks consistent patterns, versioning, and documentation, leading to integration friction and maintenance cost.

Core Features & Use Cases

  • Patterns and guidelines for REST, GraphQL, gRPC, and WebSocket API design.
  • Versioning, pagination, error handling, and OpenAPI/Swagger documentation.
  • Use cases include designing new APIs, refactoring, and establishing standard conventions across teams.

Quick Start

Provide a complete API design blueprint covering REST, GraphQL, gRPC, and WebSocket choices, versioning, and documentation.

Frequently Asked Questions about api-design

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

FAQPage Schema
What is the best way to design consistent REST and GraphQL APIs?

The best way to design consistent REST and GraphQL APIs is to apply standardized patterns and guidelines for schema design, versioning, and error handling, which reduces integration friction and maintenance costs.

How do I choose between REST, GraphQL, gRPC, and WebSocket for my API?

Choose between REST, GraphQL, gRPC, and WebSocket by evaluating standardized paradigm selection guidelines against your specific use case, ensuring your API design satisfies scalability and consistency requirements across languages and platforms.

How do I handle API versioning and pagination when refactoring existing APIs?

Handle API versioning and pagination during refactoring by applying standardized design patterns and guidelines, ensuring consistent schema structures and minimizing integration friction across REST, GraphQL, gRPC, and WebSocket paradigms.

Can I generate OpenAPI and Swagger documentation for gRPC and WebSocket APIs?

Yes, you can establish standard conventions for OpenAPI and Swagger documentation across gRPC and WebSocket APIs by applying consistent design blueprints that satisfy documentation best practices.

Does this API design approach work for establishing standard conventions across multiple teams?

Yes, this approach works for establishing standard conventions across teams by providing a complete API design blueprint covering versioning, error handling, and documentation patterns across REST, GraphQL, gRPC, and WebSocket paradigms.

Why do my REST and GraphQL APIs lack consistent patterns and documentation?

REST and GraphQL APIs lack consistent patterns and documentation when standardized design guidelines are missing, leading to increased integration friction and higher long-term maintenance costs.