api-design

name	api-design
description	API design principles for REST, GraphQL, and gRPC
category	skill
allowed-tools	Read, Write, Glob, Grep, Bash
user-invocable	true
context	inject

API Design Skills

Overview

API design knowledge for building clean, consistent, and developer-friendly APIs. This domain covers REST, GraphQL, gRPC, documentation standards, and best practices.

API Types Comparison

┌─────────────────────────────────────────────────────────────────────────────┐
│                        API Types Comparison                                  │
├──────────────┬──────────────┬──────────────┬──────────────┬─────────────────┤
│ Aspect       │ REST         │ GraphQL      │ gRPC         │ Best For        │
├──────────────┼──────────────┼──────────────┼──────────────┼─────────────────┤
│ Protocol     │ HTTP/1.1     │ HTTP/1.1     │ HTTP/2       │                 │
│ Format       │ JSON/XML     │ JSON         │ Protobuf     │                 │
│ Schema       │ Optional     │ Required     │ Required     │                 │
│              │ (OpenAPI)    │ (SDL)        │ (.proto)     │                 │
│ Caching      │ HTTP native  │ Complex      │ Manual       │                 │
│ Real-time    │ Polling/SSE  │ Subscriptions│ Streaming    │                 │
│ Learning     │ Easy         │ Medium       │ Hard         │                 │
├──────────────┼──────────────┼──────────────┼──────────────┼─────────────────┤
│ Use Cases    │ Public APIs  │ Flexible     │ Microservices│                 │
│              │ CRUD apps    │ Mobile apps  │ Low latency  │                 │
│              │ Web services │ Aggregation  │ High perf    │                 │
└──────────────┴──────────────┴──────────────┴──────────────┴─────────────────┘

Categories

REST

• REST principles and HATEOAS
• Resource naming conventions
• HTTP methods semantics
• Status codes usage
• Pagination strategies
• Filtering and sorting
• API versioning

GraphQL

• Schema design
• Queries and mutations
• Resolvers
• Subscriptions
• N+1 problem solutions

gRPC

• Protocol Buffers
• Service definitions
• Streaming patterns
• Error handling

Documentation

• OpenAPI/Swagger
• API documentation best practices
• Examples and SDKs

Patterns

• Request/Response design
• Error handling
• Authentication patterns
• Rate limiting
• Idempotency

Best Practices

• API design guidelines
• Backwards compatibility
• API evolution strategies

REST Maturity Model (Richardson)

┌─────────────────────────────────────────────────────────────────┐
│                   REST Maturity Model                            │
├─────────────────────────────────────────────────────────────────┤
│                                                                  │
│  Level 3: Hypermedia Controls (HATEOAS)                         │
│           ├── Self-documenting APIs                              │
│           ├── Discoverability via links                          │
│           └── Decoupled client-server evolution                  │
│                        ↑                                         │
│  Level 2: HTTP Verbs + Status Codes                             │
│           ├── GET, POST, PUT, PATCH, DELETE                     │
│           ├── Proper status codes (200, 201, 404, etc.)         │
│           └── Safe and idempotent methods                        │
│                        ↑                                         │
│  Level 1: Resources                                              │
│           ├── Multiple URIs for different resources              │
│           ├── /users, /orders, /products                        │
│           └── Still using single HTTP verb                       │
│                        ↑                                         │
│  Level 0: The Swamp of POX                                      │
│           ├── Single URI for all operations                      │
│           ├── POST /api with action in body                     │
│           └── RPC-style over HTTP                                │
│                                                                  │
└─────────────────────────────────────────────────────────────────┘

API Design Decision Tree

┌─────────────────────────────────────────────────────────────────┐
│                 Which API Style to Choose?                       │
├─────────────────────────────────────────────────────────────────┤
│                                                                  │
│  Start Here                                                      │
│      │                                                           │
│      ▼                                                           │
│  Public API for third parties?                                  │
│      │                                                           │
│      ├── Yes → REST (with OpenAPI)                              │
│      │         • Easy to understand                              │
│      │         • Good tooling                                    │
│      │         • HTTP caching                                    │
│      │                                                           │
│      └── No → Internal/Microservices?                           │
│               │                                                  │
│               ├── Yes → Need real-time?                         │
│               │         │                                        │
│               │         ├── Yes → gRPC streaming                │
│               │         │                                        │
│               │         └── No → High performance?              │
│               │                  │                               │
│               │                  ├── Yes → gRPC                 │
│               │                  └── No → REST                  │
│               │                                                  │
│               └── No → Mobile/Web frontend?                     │
│                        │                                         │
│                        ├── Multiple clients? → GraphQL          │
│                        ├── Complex queries? → GraphQL           │
│                        └── Simple CRUD? → REST                  │
│                                                                  │
└─────────────────────────────────────────────────────────────────┘

Quick Reference

HTTP Methods

Method	Idempotent	Safe	Cacheable	Request Body
GET	Yes	Yes	Yes	No
POST	No	No	No	Yes
PUT	Yes	No	No	Yes
PATCH	No*	No	No	Yes
DELETE	Yes	No	No	Optional

Common Status Codes

Code	Name	Usage
200	OK	Successful GET, PUT, PATCH
201	Created	Successful POST (resource created)
204	No Content	Successful DELETE
400	Bad Request	Invalid syntax, validation error
401	Unauthorized	Missing/invalid authentication
403	Forbidden	Valid auth, no permission
404	Not Found	Resource doesn't exist
409	Conflict	Resource conflict
422	Unprocessable	Semantic errors
429	Too Many Requests	Rate limited
500	Internal Error	Server error

Skills Index

REST

Skill	Description
rest-principles	Core REST constraints and design
resource-naming	URI design and resource naming
http-methods	HTTP verb semantics
status-codes	HTTP status code usage
pagination	Pagination strategies
filtering-sorting	Query parameters design
versioning	API versioning approaches

GraphQL

Skill	Description
graphql-basics	GraphQL fundamentals
schema-design	Type system and schema
resolvers	Resolver patterns
mutations	Write operations
subscriptions	Real-time updates

gRPC

Skill	Description
grpc-basics	gRPC fundamentals
protobuf	Protocol Buffers
streaming	Streaming patterns

Documentation

Skill	Description
openapi-swagger	OpenAPI specification
api-documentation	Documentation best practices
examples	Code examples and SDKs

Patterns

Skill	Description
request-response	Request/response design
error-handling	Error handling patterns
authentication	Auth patterns
rate-limiting	Rate limiting strategies
idempotency	Idempotent operations

Best Practices

Skill	Description
api-guidelines	General API guidelines
backwards-compatibility	Maintaining compatibility
api-evolution	Evolving APIs over time