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