api-design-fundamentals

# API Design Fundamentals

Guidance for designing effective APIs including protocol selection, resource modeling, and best practices.

## When to Use This Skill

- Choosing between REST, GraphQL, and gRPC
- Designing resource models and endpoints
- Understanding API design best practices
- Creating consistent API conventions
- Designing for developer experience

## Protocol Comparison

### REST (Representational State Transfer)

**Best for:** CRUD operations, public APIs, broad client compatibility

```text
Characteristics:
- Resource-oriented (nouns, not verbs)
- HTTP methods map to operations (GET, POST, PUT, DELETE)
- Stateless
- Cacheable responses
- Self-descriptive messages

Example:
GET    /users          - List users
GET    /users/{id}     - Get user
POST   /users          - Create user
PUT    /users/{id}     - Update user
DELETE /users/{id}     - Delete user
```

**Strengths:**

- Simple, widely understood
- Excellent caching support
- Works with any HTTP client
- Good for public APIs

**Weaknesses:**

- Over-fetching (get more data than needed)
- Under-fetching (multiple requests needed)
- No built-in schema/types

### GraphQL

**Best for:** Complex data requirements, mobile apps, aggregating multiple services

```text
Characteristics:
- Single endpoint
- Client specifies exact data needed
- Strongly typed schema
- Introspection support
- Real-time with subscriptions

Example:
query {
  user(id: "123") {
    name
    email
    posts(limit: 5) {
      title
      comments { count }
    }
  }
}
```

**Strengths:**

- No over/under-fetching
- Strong typing and schema
- Excellent developer tooling
- Version-free evolution

**Weaknesses:**

- Caching complexity
- N+1 query problems
- Learning curve
- Not ideal for simple APIs

### gRPC

**Best for:** Internal microservices, high-performance, polyglot systems

```text
Characteristics:
- Protocol Buffers (binary format)
- HTTP/2 transport
- Bi-directional streaming
- Code generation
- Strong typing

Example (prot