skills.rest
ragnarula
ragnarulaCOMMUNITY
Explore all skills by this author →
GitHub

api-design

Design consumer-centric APIs for REST, GraphQL, gRPC, and SDKs.

Updated Aug 27, 2026
Search Tags:#design#versioning#documentation#GraphQL#REST#APIs#contract
One-click install
npx skills add https://github.com/ragnarula/cc-plugins --skill api-design-ragnarula
Or copy as Structured Prompt for Agent▼
Please help me install this Agent Skill.
Skill: api-design
Source: https://github.com/ragnarula/cc-plugins/tree/main/sdd/skills/api-design
Command: npx skills add https://github.com/ragnarula/cc-plugins --skill api-design-ragnarula

SYSTEM DOCUMENTATION & REQUIREMENTS

What problem does it solve?

API design is about shaping interfaces from the consumer perspective to produce usable, evolvable contracts that stand the test of time.

Core Features & Use Cases

  • Consumer-centric design: Prioritize usability, consistency, and clear boundaries for REST, GraphQL, gRPC, and SDK interfaces.
  • Versioning & evolution: Establish stable versioning strategies and deprecation plans to minimize breaking changes.
  • Documentation & ergonomics: Align docs, examples, and error handling with implemented endpoints to reduce learning curve.
  • Use Case: Imagine a developer integrating a new service; this skill provides guidelines to design intuitive resources, clear error schemas, and version-aware endpoints.

Quick Start

Design a minimal Todo API with CRUD endpoints and sample request/response bodies.

Frequently Asked Questions about api-design

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

FAQPage Schema
How do I design a REST API that won't break when I need to evolve it?▼

Design REST APIs from the consumer's perspective using versioning strategies and deprecation plans that minimize breaking changes. Establish stable resource patterns, consistent error handling, and pagination approaches upfront to support safe evolution without disrupting existing integrations.

What's the best way to document an API so developers can integrate it quickly?▼

Align documentation and examples directly with implemented endpoints, clear error schemas, and version-aware behavior. Consumer-centric design reduces learning curve by making resources intuitive and error messages actionable, so developers integrate with confidence.

Can I apply API design principles to GraphQL and gRPC, or just REST?▼

API design principles apply across REST, GraphQL, gRPC services, and SDKs. The same contract creation, ergonomics, and versioning strategies guide resource design and error handling consistently, regardless of the protocol or interface type you're using.

How do I handle versioning and deprecation without breaking existing client integrations?▼

Establish versioning strategies and deprecation plans during design that allow stable evolution. Consumer-centric design anticipates integration patterns and defines clear boundaries, so you can retire old endpoints or schemas without surprise disruptions.

What makes an API contract stable and trustworthy for long-term use?▼

A stable API contract prioritizes consumer usability, consistent error handling, and clear resource boundaries. By designing from the consumer's perspective with documented versioning and evolution plans, you create interfaces that stand the test of time and users can depend on.

Related Skills

Explore More Software Engineering Skills→
jacob-balslevjacob-balslev
1

system-interface-contracts

Define stable interface contracts with fields, invariants, and versioning rules.

Community
Advanced
canvas-medicalcanvas-medical
2

plugin-api-server-security

Audit Canvas plugin API endpoints for authentication and authorization.

Official
Basic
ccfccf

openapi-spec-generation

Generate and validate OpenAPI 3.1 specifications from design or code sources.

Community
Advanced
Eigo-Mt-FujiEigo-Mt-Fuji

api-designer

Generate OpenAPI, GraphQL SDL, and Protocol Buffer definitions for APIs.

Community
Advanced