System Designer
Back to Fundamentals

API Design Principles

18 min read•Intermediate
Not Started
Loading...

Master the art of designing APIs that developers love to use. Learn REST principles, GraphQL fundamentals, and best practices for creating scalable, maintainable APIs.

REST API Design Principles

REST (Representational State Transfer) provides a proven architectural style for web APIs. Following these principles creates APIs that are intuitive, cacheable, and scalable.

1

Resource-Based URLs

URLs should represent resources, not actions

✓ Good
/api/users/123/orders
✗ Bad
/api/getUserOrders?userId=123
Why: Clear resource hierarchy, intuitive navigation, cacheable
2

HTTP Methods

Use appropriate HTTP verbs for different operations

✓ Good
GET /users/123
✗ Bad
POST /getUser
Why: Follows web standards, enables proper caching, clear intent
3

Stateless Operations

Each request contains all information needed

✓ Good
Authorization: Bearer token123
✗ Bad
Relies on server session state
Why: Scalable, cacheable, reliable across distributed systems
4

Consistent Response Format

Standardize response structure across all endpoints

✓ Good
{"data": {...}, "error": null, "meta": {...}}
✗ Bad
Different structure per endpoint
Why: Predictable client code, easier testing, better DX

HTTP Status Codes Reference

Proper status codes help clients understand what happened and how to respond. Consistent usage across your API improves developer experience.

200 OK
Successful GET, PUT requests
User profile retrieved
201 Created
Successful POST with resource creation
New user account created
204 No Content
Successful DELETE, some PUT operations
User deleted successfully
400 Bad Request
Invalid request format or parameters
Missing required field "email"
401 Unauthorized
Authentication required or failed
Invalid API key
403 Forbidden
Authenticated but not authorized
Cannot delete other user's data
404 Not Found
Resource does not exist
User ID 999 not found
429 Too Many Requests
Rate limit exceeded
Max 100 requests per minute
500 Internal Server Error
Unexpected server error
Database connection failed

Status Code Categories

2xx Success:

Request succeeded, operation completed

4xx Client Error:

Client mistake, fix request and retry

5xx Server Error:

Server issue, client can retry later

REST vs GraphQL

Both REST and GraphQL have their strengths. Choose based on your specific requirements, team expertise, and client needs.

REST Advantages

  • • Simple to understand: HTTP methods map to operations
  • • Great caching: HTTP caching works out of the box
  • • Mature ecosystem: Extensive tooling and knowledge
  • • Multiple formats: JSON, XML, HTML support
  • • Stateless: Easy to scale horizontally

Best for:

  • • Simple CRUD applications
  • • Public APIs
  • • Microservices architecture
  • • Teams new to API development

GraphQL Advantages

  • • Flexible queries: Clients specify exactly what they need
  • • Single endpoint: No need for multiple API calls
  • • Strong typing: Schema-first development
  • • Real-time: Built-in subscription support
  • • Introspection: Self-documenting APIs

Best for:

  • • Complex data relationships
  • • Mobile applications (bandwidth optimization)
  • • Rapid frontend development
  • • Real-time applications

Performance Comparison

Caching
5/5REST
2/5GraphQL
Over-fetching
2/5REST
5/5GraphQL
Network Requests
2/5REST
5/5GraphQL
Learning Curve
5/5REST
3/5GraphQL

API Design Checklist

Design Principles

  • ☐ Use resource-based URLs
  • ☐ Follow HTTP method semantics
  • ☐ Return consistent response formats
  • ☐ Use appropriate status codes
  • ☐ Design for idempotency

Production Readiness

  • ☐ Implement authentication & authorization
  • ☐ Add rate limiting and throttling
  • ☐ Validate all inputs
  • ☐ Use HTTPS everywhere
  • ☐ Create comprehensive documentation

🎯 API Design Successes and Failures

Learn from real-world API design decisions and their impact on developer adoption

Scenarios

Stripe API: Developer-First Design
How Stripe became the gold standard for API design and developer experience
Twitter API v1 to v2 Migration Pain
How Twitter's API redesign caused developer ecosystem disruption
Netflix API: Scaling to 1000+ Use Cases
How Netflix evolved from simple REST to GraphQL-like custom solutions
GitHub API: Consistency Across Growth
How GitHub maintained API quality while rapidly expanding features
Facebook Graph API: Complexity vs Power
How Facebook balanced powerful data access with API complexity
Slack API: Platform Strategy Success
How Slack's API strategy built a thriving app ecosystem

Context

How Stripe became the gold standard for API design and developer experience

Metrics

Developer Adoption
95% satisfaction
API Consistency
RESTful throughout
Documentation Quality
Interactive examples
Time to Integration
15 minutes avg

Outcome

Stripe's API-first approach drove massive developer adoption. Clear docs, consistent patterns, and excellent error messages made integration effortless.

Key Lessons

  • •Invest heavily in documentation with live examples and code samples
  • •Consistent naming conventions and response formats across all endpoints
  • •Descriptive error messages with specific guidance on how to fix issues
  • •Webhooks and idempotency keys essential for payment processing reliability

📝 API Design Quiz

1 of 5Current: 0/5

Which URL design follows REST principles best for getting a user's orders?