/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                  │
│               │                                                  │
│