What is REST?

REST (Representational State Transfer) is an architectural style for designing networked applications, introduced by Roy Fielding in his 2000 doctoral dissertation. It is not a protocol or standard - it is a set of constraints that, when followed, produce systems that are scalable, simple, and maintainable.

The Six REST Constraints

1. Client-Server: Separate the user interface (client) from data storage and business logic (server). This allows each to evolve independently.

2. Stateless: Each request from client to server must contain all the information needed to process it. The server does not store session state between requests. Authentication tokens, for example, are sent with every request.

3. Cacheable: Responses must indicate whether they can be cached. Proper caching eliminates redundant interactions and improves performance.

4. Uniform Interface: All resources are accessed through a consistent, standardized interface (URLs + HTTP methods). This simplifies the architecture and enables independent evolution.

5. Layered System: The client cannot tell whether it is connected directly to the server or to an intermediary (load balancer, CDN, API gateway). Each layer only knows about the layer it interacts with.

6. Code on Demand (optional): Servers can extend client functionality by sending executable code (e.g., JavaScript). This is the only optional constraint.

REST vs RESTful

• REST is the architectural style.
• RESTful describes an API that follows REST constraints.
• In practice, most APIs marketed as "REST" are actually "REST-ish" - they use HTTP and JSON but may violate some constraints (e.g., storing session state on the server).

Resources: The Core Abstraction

In REST, everything is a resource - a user, a post, an order, a payment. Each resource has:

• A unique identifier (URL)
• Representations (JSON, XML, etc.)
• Standard operations (HTTP methods)

URL Design & Resource Naming

URL design is the most visible part of an API. Well-designed URLs are intuitive, predictable, and self-documenting.

Core Principles

1. Use nouns, not verbs: URLs represent resources (things), not actions.

   • Good: GET /users/42
   • Bad: GET /getUser?id=42

2. Use plural nouns: Collections should be plural for consistency.

   • Good: /users, /orders, /products
   • Bad: /user, /order, /product

3. Use hierarchy for relationships: Nest related resources.

   • GET /users/42/orders - all orders for user 42
   • GET /users/42/orders/7 - order 7 for user 42
   • Limit nesting to 2 levels. Deeper nesting becomes unwieldy: /users/42/orders/7/items/3/reviews is too deep.

4. Use kebab-case: Separate words with hyphens.

   • Good: /order-items, /user-profiles
   • Bad: /orderItems, /order_items

5. No trailing slashes: Be consistent. Pick one convention and stick to it.

   • Preferred: /users/42 (no trailing slash)

URL Design Examples

# Collection operations
GET    /api/v1/users          - List all users
POST   /api/v1/users          - Create a new user

# Single resource operations
GET    /api/v1/users/42       - Get user 42
PUT    /api/v1/users/42       - Replace user 42
PATCH  /api/v1/users/42       - Partially update user 42
DELETE /api/v1/users/42       - Delete user 42

# Nested resources
GET    /api/v1/users/42/posts       - List user 42's posts
POST   /api/v1/users/42/posts       - Create a post for user 42
GET    /api/v1/users/42/posts/101    - Get post 101 by user 42

# Filtering, sorting, pagination via query parameters
GET    /api/v1/users?role=admin&sort=created_at&order=desc&page=2&limit=20

# Search
GET    /api/v1/users/search?q=john

# Actions that don't map to CRUD (use sparingly)
POST   /api/v1/orders/42/cancel
POST   /api/v1/users/42/reset-password

What About Actions That Are Not CRUD?

Some operations do not fit neatly into create/read/update/delete:

• Use POST with a descriptive sub-resource: POST /orders/42/cancel
• Model the action as a resource: Instead of POST /users/42/activate, create an activation resource: POST /users/42/activations
• Do not use GET for side effects: GET /users/42/delete is a REST anti-pattern. GET must be safe (no side effects).

HTTP Methods & Status Codes in Practice

Mapping CRUD to HTTP Methods

Choosing the Right Status Code

401 vs 403: A Common Confusion

• 401 Unauthorized: "I don't know who you are. Please authenticate." (Missing or invalid token)
• 403 Forbidden: "I know who you are, but you are not allowed to do this." (Valid token, insufficient permissions)

Despite the confusing name, 401 means unauthenticated, and 403 means unauthorized.

Pagination, Filtering & Sorting

Any endpoint that returns a list of resources must support pagination. Returning 10 million users in a single response is a guaranteed way to crash your server and your client.

Pagination Strategies

1. Offset-Based Pagination

GET /api/v1/users?page=3&limit=20

How it works: Skip (page - 1) * limit rows, return the next limit rows. Pros: Simple, allows jumping to any page. Cons: Performance degrades on large datasets (SQL's OFFSET scans skipped rows). Inconsistent results if data changes between pages (items shift).

2. Cursor-Based Pagination

GET /api/v1/users?cursor=eyJpZCI6MTAwfQ&limit=20

How it works: The cursor is an opaque token (often a Base64-encoded ID or timestamp) pointing to the last item of the previous page. The server fetches items after the cursor. Pros: Consistent performance regardless of page depth. Stable results even when data changes. Cons: Cannot jump to a specific page. More complex to implement.

3. Keyset Pagination

GET /api/v1/users?after_id=100&limit=20
-- SQL: SELECT * FROM users WHERE id > 100 ORDER BY id LIMIT 20

How it works: Similar to cursor-based, but the cursor is a visible field value (like an ID or timestamp) rather than an opaque token. Pros: Efficient (uses index), easy to understand. Cons: Requires a unique, sortable field.

Pagination Response Format

{
    "data": [...],
    "pagination": {
        "total": 1542,
        "limit": 20,
        "offset": 40,
        "hasMore": true,
        "nextCursor": "eyJpZCI6MTYwfQ"
    }
}

Which Pagination Strategy to Choose?

Filtering and Sorting

# Filtering
GET /api/v1/products?category=electronics&price_min=100&price_max=500&in_stock=true

# Sorting
GET /api/v1/products?sort=price&order=asc
GET /api/v1/products?sort=-created_at  (prefix with - for descending)

# Combined
GET /api/v1/products?category=electronics&sort=-price&limit=20&cursor=abc123

Best practice: Always define a default sort order (usually by creation date, descending). Never return unordered results - it makes pagination unpredictable.

API Versioning

APIs evolve. You will add new fields, change behavior, and occasionally make breaking changes. Versioning lets you evolve without breaking existing clients.

Versioning Strategies

1. URL Path Versioning (Most Common)

GET /api/v1/users
GET /api/v2/users

Pros: Explicit, easy to understand, easy to route at the API gateway/load balancer level. Cons: Duplicates routes. Clients must update URLs to adopt new versions. Used by: Stripe, Twilio, GitHub (partially).

2. Query Parameter Versioning

GET /api/users?version=2

Pros: Same URL, easy to default to latest version. Cons: Less visible, can be forgotten. Harder to cache (cache keys must include the parameter).

3. Header Versioning

GET /api/users
Accept: application/vnd.myapi.v2+json

Pros: Clean URLs, follows HTTP content negotiation semantics. Cons: Hidden from URL inspection, harder to test in a browser, less discoverable. Used by: GitHub API.

4. Date-Based Versioning

GET /api/users
Stripe-Version: 2024-01-15

Pros: Fine-grained, allows gradual rollout of changes tied to specific dates. Cons: Complex to manage internally, requires mapping dates to behavior. Used by: Stripe.

Best Practice: URL Path Versioning

For most APIs, URL path versioning (/v1/, /v2/) is the recommended approach because:

• It is immediately visible in every request
• API gateways can route by path prefix
• It is the most widely understood convention
• Caching works naturally (different URLs = different cache entries)

When to Increment the Version?

Breaking changes require a new version:

• Removing a field from the response
• Changing the type of a field
• Changing the meaning of a status code
• Requiring new mandatory parameters

Non-breaking changes do not require a new version:

• Adding a new optional field to the response
• Adding a new optional query parameter
• Adding a new endpoint
• Adding a new status code for a new scenario

Error Handling & Response Design

Consistent error handling is what separates a professional API from an amateur one. Clients need to programmatically handle errors, so the format must be predictable.

Standard Error Response Format

{
    "error": {
        "code": "VALIDATION_ERROR",
        "message": "The request body is invalid.",
        "details": [
            {
                "field": "email",
                "issue": "Must be a valid email address.",
                "value": "not-an-email"
            },
            {
                "field": "age",
                "issue": "Must be a positive integer.",
                "value": -5
            }
        ],
        "requestId": "req_abc123",
        "documentation": "https://api.example.com/docs/errors#VALIDATION_ERROR"
    }
}

Error Response Best Practices

1. Use the HTTP status code correctly: The status code (400, 404, 500) is the primary error signal. The body provides details.

2. Include a machine-readable error code: VALIDATION_ERROR, RESOURCE_NOT_FOUND, RATE_LIMIT_EXCEEDED. Clients can switch on this code without parsing human-readable messages.

3. Include a human-readable message: For developer debugging, not for end-user display.

4. Include a request ID: Essential for debugging. The client can report this ID, and you can trace it through your logs.

5. Include field-level details for validation errors: Clients need to know which fields failed and why.

6. Never expose internal details in production: Stack traces, SQL queries, internal server names - these are security risks.

Successful Response Design

// Single resource
{
    "data": {
        "id": 42,
        "name": "Alice",
        "email": "[email protected]",
        "createdAt": "2024-01-15T10:30:00Z"
    }
}

// Collection
{
    "data": [
        { "id": 1, "name": "Alice" },
        { "id": 2, "name": "Bob" }
    ],
    "pagination": {
        "total": 150,
        "limit": 20,
        "offset": 0,
        "hasMore": true
    }
}

Wrapping Responses

Always wrap your responses in a top-level object ({ "data": ... }) rather than returning a raw array. This allows you to add metadata (pagination, request ID, deprecation warnings) without breaking the response structure.

Trade-offs & When REST Falls Short

REST is the default choice for most APIs, but it has limitations that other styles address.

Over-fetching and Under-fetching

Over-fetching: GET /users/42 returns all 30 fields when the client only needs name and avatar. Wasted bandwidth, especially on mobile.

Under-fetching: To show a user's profile with their posts and followers, the client needs three separate requests:

1. GET /users/42
2. GET /users/42/posts
3. GET /users/42/followers

GraphQL solves this by letting the client specify exactly which fields and nested resources it needs in a single query.

REST vs GraphQL vs gRPC

When to Choose What

• REST: Default choice for public-facing APIs, CRUD-heavy applications, and when HTTP caching is important.
• GraphQL: When clients have diverse data needs (mobile vs web), when over-fetching is a real problem, or when you want a single endpoint for multiple resources.
• gRPC: For internal service-to-service communication where latency matters, when you want strong typing and code generation, or for streaming use cases.

REST API Design Anti-Patterns

1. Verbs in URLs: /getUsers, /createOrder - use HTTP methods instead.
2. Ignoring status codes: Returning 200 with {"error": true} in the body.
3. Inconsistent naming: Mixing /userProfiles with /order-items.
4. No pagination on list endpoints: Returning unbounded results.
5. Exposing database IDs as sequential integers: Security risk (enumeration attacks). Consider UUIDs or opaque IDs.
6. Tight coupling to database schema: API fields should not mirror database columns. The API is a contract; the database is an implementation detail.

REST API Design in Interviews

How to Design APIs in a System Design Interview

When the interviewer says "let's define the API," follow this structure:

Step 1: Identify the Resources

List the main entities in the system.

• URL shortener: urls, analytics
• Instagram: users, posts, comments, likes, follows
• Chat system: conversations, messages, users

Step 2: Define CRUD Operations

For each resource, specify the key endpoints:

POST   /api/v1/urls          - Create a short URL
GET    /api/v1/urls/:id       - Get URL details
GET    /:shortCode            - Redirect (special case)
DELETE /api/v1/urls/:id       - Delete a short URL
GET    /api/v1/urls/:id/analytics - Get click analytics

Step 3: Specify Request/Response Shapes

// POST /api/v1/urls
// Request
{ "longUrl": "https://example.com/very/long/path", "customAlias": "my-link" }

// Response (201 Created)
{ "data": { "id": "abc123", "shortUrl": "https://short.ly/my-link", "longUrl": "...", "createdAt": "..." } }

Step 4: Call Out Special Considerations

• Pagination strategy for list endpoints
• Authentication method (JWT, API key)
• Rate limiting policy
• Idempotency keys for non-idempotent operations (POST)

Quick Reference: Commonly Designed APIs