API Design Fundamentals Skill

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

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

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

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

Example (proto):
service UserService {
  rpc GetUser(GetUserRequest) returns (User);
  rpc ListUsers(ListUsersRequest) returns (stream User);
  rpc CreateUser(CreateUserRequest) returns (User);
}

Strengths:

High performance (binary, HTTP/2)
Strong contracts (protobuf)
Bi-directional streaming
Excellent for microservices

Weaknesses:

Browser support limited (needs grpc-web)
Not human-readable
Steeper learning curve
Debugging more complex

Protocol Selection Guide

Decision Tree:

Is this a public API for external developers?
├── Yes → REST (broadest compatibility)
└── No
    └── Do clients need flexible queries?
        ├── Yes → GraphQL
        └── No
            └── Is performance critical?
                ├── Yes → gRPC
                └── No → REST or GraphQL

| Factor | REST | GraphQL | gRPC | | ------ | ---- | ------- | ---- | | Public APIs | ✅ Best | ⚠️ Possible | ❌ Poor | | Mobile apps | ⚠️ OK | ✅ Best | ⚠️ Limited | | Microservices | ⚠️ OK | ⚠️ OK | ✅ Best | | Real-time | ⚠️ WebSocket | ✅ Subscriptions | ✅ Streaming | | Browser support | ✅ Native | ✅ Native | ⚠️ grpc-web | | Caching | ✅ Easy | ⚠️ Complex | ❌ Manual | | Learning curve | ✅ Low | ⚠️ Medium | ⚠️ Medium |

REST API Design Best Practices

Resource Naming

DO:
- Use nouns, not verbs: /users, /orders, /products
- Use plural form: /users (not /user)
- Use kebab-case: /user-profiles (not /userProfiles)
- Nest for relationships: /users/{id}/orders

DON'T:
- /getUsers, /createOrder (verbs)
- /user (singular)
- /user_profiles (snake_case in URLs)

HTTP Methods

| Method | Purpose | Idempotent | Safe | | ------ | ------- | ---------- | ---- | | GET | Read resource | Yes | Yes | | POST | Create resource | No | No | | PUT | Replace resource | Yes | No | | PATCH | Partial update | No* | No | | DELETE | Remove resource | Yes | No |

*PATCH can be idempotent depending on implementation

Status Codes

| Code | Meaning | When to Use | | ---- | ------- | ----------- | | 200 | OK | Successful GET, PUT, PATCH | | 201 | Created | Successful POST | | 204 | No Content | Successful DELETE | | 400 | Bad Request | Invalid request body | | 401 | Unauthorized | Missing/invalid auth | | 403 | Forbidden | Insufficient permissions | | 404 | Not Found | Resource doesn't exist | | 409 | Conflict | Resource conflict | | 422 | Unprocessable | Validation failed | | 429 | Too Many Requests | Rate limited | | 500 | Server Error | Unexpected error |

Pagination

Offset-based (simple, but problematic at scale):
GET /users?offset=20&limit=10

Cursor-based (recommended for large datasets):
GET /users?cursor=eyJpZCI6MTAwfQ&limit=10

Response:
{
  "data": [...],
  "pagination": {
    "next_cursor": "eyJpZCI6MTEwfQ",
    "has_more": true
  }
}

Filtering and Sorting

Filtering:
GET /products?category=electronics&price_min=100&price_max=500

Sorting:
GET /products?sort=price:asc,name:desc

Field selection (partial responses):
GET /users?fields=id,name,email

Error Responses

{
  "error": {
    "code": "VALIDATION_ERROR",
    "message": "Invalid request parameters",
    "details": [
      {
        "field": "email",
        "message": "Invalid email format"
      }
    ],
    "request_id": "req_abc123"
  }
}

GraphQL Best Practices

Schema Design

# Use clear, descriptive types
type User {
  id: ID!
  email: String!
  profile: UserProfile
  posts(first: Int, after: String): PostConnection!
}

# Use connections for pagination
type PostConnection {
  edges: [PostEdge!]!
  pageInfo: PageInfo!
}

# Use input types for mutations
input CreateUserInput {
  email: String!
  name: String!
}

Query Complexity Limits

Protect against expensive queries:
- Depth limiting (max nesting level)
- Complexity scoring (assign costs to fields)
- Query timeout
- Rate limiting per client

N+1 Prevention

Use DataLoader pattern:
- Batch requests for same type
- Cache within single request
- Prevents N+1 database queries

gRPC Best Practices

Service Design

// Keep messages focused
message User {
  string id = 1;
  string email = 2;
  string name = 3;
}

// Use request/response wrappers
message GetUserRequest {
  string id = 1;
}

message GetUserResponse {
  User user = 1;
}

// Support streaming for large datasets
service UserService {
  rpc GetUser(GetUserRequest) returns (GetUserResponse);
  rpc ListUsers(ListUsersRequest) returns (stream User);
}

Error Handling

Use standard gRPC status codes:
- OK (0): Success
- INVALID_ARGUMENT (3): Bad request
- NOT_FOUND (5): Resource missing
- PERMISSION_DENIED (7): Forbidden
- INTERNAL (13): Server error
- UNAVAILABLE (14): Service down

API Evolution

Backward Compatibility Rules

Safe changes (backward compatible):
- Adding new endpoints
- Adding optional fields
- Adding new enum values (at end)
- Relaxing validation rules

Breaking changes (avoid):
- Removing endpoints
- Removing fields
- Changing field types
- Renaming fields
- Adding required fields

Deprecation Strategy

1. Mark as deprecated (add header/annotation)
2. Document migration path
3. Set sunset date
4. Monitor usage
5. Remove after sunset

Related Skills

rate-limiting-patterns - API protection
idempotency-patterns - Reliable APIs
api-versioning - API evolution

Agent Skills: API Design Fundamentals

Install this agent skill to your local

Skill Files