RESTful API Design: Best Practices for Building Web APIs

REST (Representational State Transfer) is the dominant approach for designing web APIs. It provides a structured way to expose resources over HTTP. Understanding REST principles helps you build APIs that are intuitive, scalable, and maintainable.

The HTTP/HTTPS protocol post covers HTTP methods and status codes. This post focuses on applying those concepts to API design.

---

Introduction

REST is an architectural style, not a specification. It was defined by Roy Fielding in 2000. The key idea: treat everything as a resource that clients can interact with through standard HTTP operations.

REST APIs expose resources through URLs. The HTTP method indicates the action:

graph LR
    A[Client] -->|GET /users| B[Read users]
    A -->|POST /users| C[Create user]
    A -->|PUT /users/123| D[Update user]
    A -->|DELETE /users/123| E[Delete user]

---

Resource Naming & URL Design

Resource Naming

Resource names are the foundation of REST API design. Good resource names are:

• Nouns, not verbs - /users not /getUsers
• Plural - /users not /user
• Hierarchical - /users/123/orders for users orders
• Consistent - Same pattern throughout

# Good resource naming
GET /users              # List users
GET /users/123           # Get user 123
GET /users/123/orders   # Get orders for user 123
POST /users             # Create user
PUT /users/123          # Update user 123
DELETE /users/123       # Delete user 123

# Bad naming (mixing verbs and nouns)
GET /getUsers
GET /getUserById/123
POST /createUser

Nested Resources

Nested resources express relationships:

# A user posts
GET /users/123/posts

# A post comments
GET /posts/456/comments

# Limit nesting depth - typically 2 levels is practical
GET /users/123/posts/789/comments  # Too deep

---

HTTP Methods & Status Codes

Core HTTP Methods

REST APIs use HTTP methods to indicate actions. The primary methods are:

GET

Retrieves resources. GET requests should be safe (no side effects) and idempotent.

GET /users
GET /users/123

POST

Creates new resources. Each POST request typically creates one resource.

POST /users
Content-Type: application/json

{"name": "Alice", "email": "alice@example.com"}

Response includes the created resource and a 201 status code:

HTTP/1.1 201 Created
Location: /users/124

PATCH

Partially updates a resource. Only the specified fields change.

PATCH /users/123
Content-Type: application/json

{"email": "alice.new@example.com"}

DELETE

Removes a resource.

DELETE /users/123

Idempotency Design Patterns

Idempotency ensures that making the same request multiple times produces the same result. This matters because networks fail — clients may retry requests without knowing if the first attempt succeeded.

Safe Retries with Idempotency Keys

For POST requests (which are not naturally idempotent), clients can include an idempotency key:

POST /payments
Idempotency-Key: a1b2c3d4-e5f6-7890-abcd-ef1234567890
Content-Type: application/json

{"amount": 100, "currency": "USD", "source": "card_123"}

The server stores the idempotency key with the response. If the client retries with the same key, the original response is returned without re-processing:

HTTP/1.1 201 Created
Idempotency-Replayed: true
Location: /payments/999

{"id": 999, "status": "completed", "amount": 100}

Implementing Idempotency Storage

Use a key-value store (Redis, DynamoDB) with TTL:

async function processPayment(payment, idempotencyKey) {
  // Check if already processed
  const cached = await redis.get(`idem:${idempotencyKey}`);
  if (cached) {
    return JSON.parse(cached);
  }

  // Process the payment
  const result = await billing.charge(payment);

  // Cache the result for 24 hours
  await redis.setex(`idem:${idempotencyKey}`, 86400, JSON.stringify(result));

  return result;
}

Idempotency by HTTP Method

Method	Natural Idempotency	Notes
GET	Yes	Reading a resource never changes it
PUT	Yes	Replacing with the same data is idempotent
DELETE	Yes	Deleting twice returns 404, but resource is gone
PATCH	Yes (in practice)	Same partial update applied twice has same result
POST	No	Each POST creates a new resource; requires idempotency key

Idempotency Key Best Practices

• Use UUIDs or similar high-entropy keys — never reuse keys for different requests
• Store keys with enough TTL to cover client retry windows (at least 24 hours)
• Return 422 if the request body is invalid (don’t process, but also don’t cache errors)
• Distinguish between “replayed response” (original result) and “new response” (fresh processing)

Status Codes

REST APIs should use appropriate HTTP status codes:

Success Codes

Code	Meaning	When to use
200	OK	Successful GET, PUT, PATCH
201	Created	Successful POST creating resource
204	No Content	Successful DELETE

Error Codes

Code	Meaning	When to use
400	Bad Request	Malformed request body
401	Unauthorized	Missing or invalid authentication
403	Forbidden	Authenticated but not authorized
404	Not Found	Resource does not exist
409	Conflict	Resource conflict (duplicate, state conflict)
422	Unprocessable Entity	Validation errors
500	Internal Server Error	Unexpected server error

// Example: Successful response
{
  "id": 123,
  "name": "Alice",
  "email": "alice@example.com"
}

// Example: Error response
{
  "error": "validation_error",
  "message": "Email is required",
  "details": [
    { "field": "email", "message": "This field is required" }
  ]
}

---

Request & Response Design

Request Parameters

Content Type

Always specify content type for requests with bodies:

POST /users
Content-Type: application/json

Pagination

For endpoints returning lists, use pagination:

GET /users?page=2&limit=20

Response includes pagination metadata:

{
  "data": [...],
  "pagination": {
    "page": 2,
    "limit": 20,
    "total": 100,
    "totalPages": 5
  }
}

Filtering and Sorting

Support filtering and sorting through query parameters:

# Filter by status
GET /orders?status=pending

# Filter by multiple fields
GET /orders?status=shipped&customer_id=456

# Sort by field
GET /users?sort=created_at&order=desc

Field Selection

Let clients request specific fields:

GET /users?fields=id,name,email

HATEOAS Implementation

HATEOAS (Hypermedia As The Engine Of Application State) is a REST constraint where clients interact through hypermedia links included in responses. Instead of clients constructing URLs, they follow links the server provides.

Why HATEOAS?

Without HATEOAS, clients hardcode URL patterns. When your API changes, clients break. With HATEOAS, clients discover actions dynamically:

// Response with hypermedia links
{
  "id": 123,
  "name": "Alice Smith",
  "email": "alice@example.com",
  "_links": {
    "self": { "href": "/users/123" },
    "orders": { "href": "/users/123/orders" },
    "cancel": { "href": "/users/123", "method": "DELETE" }
  }
}

A client encountering this response knows it can navigate to orders or cancel the user without hardcoding those URLs.

Designing Hypermedia Links

Use a consistent link structure:

"_links": {
  "self": { "href": "/users/123" },
  "collection": { "href": "/users" },
  "related": {
    "orders": { "href": "/users/123/orders" },
    "payment-methods": { "href": "/users/123/payment-methods" }
  },
  "actions": {
    "update": { "href": "/users/123", "method": "PUT" },
    "deactivate": { "href": "/users/123/deactivate", "method": "POST" }
  }
}

Practical Implementation

For collections, include pagination links:

{
  "data": [...],
  "_links": {
    "self": { "href": "/users?page=2&limit=20" },
    "first": { "href": "/users?page=1&limit=20" },
    "prev": { "href": "/users?page=1&limit=20" },
    "next": { "href": "/users?page=3&limit=20" },
    "last": { "href": "/users?page=10&limit=20" }
  },
  "pagination": {
    "page": 2,
    "limit": 20,
    "total": 200
  }
}

Not all APIs need HATEOAS. For simple machine-to-machine integrations, explicit URLs are easier to work with. But for API longevity and self-documenting interfaces, hypermedia is worth the effort.

---

API Versioning & Error Handling

API Versioning

APIs need to evolve without breaking existing clients. Versioning provides a way to introduce changes.

URL Path Versioning

# Most common approach
GET /v1/users
GET /v2/users

Header Versioning

GET /users
Accept: application/vnd.example.v2+json

Query Parameter Versioning

GET /users?version=2

URL path versioning is the most common because it is explicit and easy to test.

The API Versioning Strategies post covers this topic in depth.

Error Handling

Consistent error responses help clients handle failures:

// Standard error format
{
  "error": {
    "code": "RESOURCE_NOT_FOUND",
    "message": "The requested user does not exist",
    "details": {
      "resource": "user",
      "id": 999
    }
  }
}

Include enough information for debugging but do not leak sensitive details.

Handling Validation Errors

{
  "error": {
    "code": "VALIDATION_ERROR",
    "message": "Request validation failed",
    "details": [
      { "field": "email", "message": "Invalid email format" },
      { "field": "name", "message": "Name must be at least 2 characters" }
    ]
  }
}

---

Authentication & Security

Authentication

API Keys

Simple but limited. Suitable for server-to-server communication.

GET /users
X-API-Key: your-api-key-here

JWT (JSON Web Tokens)

Stateless tokens with embedded user information. Common for modern applications.

GET /users
Authorization: Bearer eyJhbG...s...

OAuth 2.0

For APIs accessed by third-party applications. More complex but more powerful.

GET /user
Authorization: Bearer access...auth

---

Documentation & Rate Limiting

API Documentation Deep Dive

OpenAPI (formerly Swagger) is the standard for REST API documentation. A well-structured spec enables client generation, testing tools, and interactive documentation.

OpenAPI Document Structure

openapi: 3.1.0
info:
  title: User Management API
  version: 2.0.0
  description: RESTful API for user lifecycle management

paths:
  /users:
    get:
      summary: List users
      parameters:
        - name: page
          in: query
          schema:
            type: integer
            default: 1
        - name: limit
          in: query
          schema:
            type: integer
            default: 20
            maximum: 100
      responses:
        "200":
          description: Paginated user list
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/UserList"
    post:
      summary: Create user
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/CreateUser"
      responses:
        "201":
          description: User created
          headers:
            Location:
              schema:
                type: string
              description: URL of created user
        "422":
          description: Validation error
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ValidationError"

components:
  schemas:
    UserList:
      type: object
      properties:
        data:
          type: array
          items:
            $ref: "#/components/schemas/User"
        pagination:
          $ref: "#/components/schemas/Pagination"
    User:
      type: object
      properties:
        id:
          type: integer
        name:
          type: string
        email:
          type: string
          format: email
    Pagination:
      type: object
      properties:
        page:
          type: integer
        limit:
          type: integer
        total:
          type: integer
    CreateUser:
      type: object
      required:
        - name
        - email
      properties:
        name:
          type: string
          minLength: 2
        email:
          type: string
          format: email
    ValidationError:
      type: object
      properties:
        error:
          type: object
          properties:
            code:
              type: string
            message:
              type: string
            details:
              type: array
              items:
                type: object
                properties:
                  field:
                    type: string
                  message:
                    type: string

Documentation-First Workflow

The documentation-first approach designs the API contract before writing code:

1. Write the OpenAPI spec — define endpoints, request/response shapes, error codes
2. Review with stakeholders — frontend teams, API consumers, product managers
3. Generate client SDKs — auto-generate libraries for Python, TypeScript, etc.
4. Implement to spec — code against the agreed contract
5. Validate — use automated tests to ensure implementation matches spec

This catches design issues before you write a line of implementation code.

Interactive Documentation with Swagger UI

Add Swagger UI as a route in your Express app:

// Express.js example
import swaggerUi from "swagger-ui-express";
import YAML from "yamljs";

const spec = YAML.load("./openapi.yaml");

app.use("/api-docs", swaggerUi.serve, swaggerUi.setup(spec));

Now at https://api.example.com/api-docs, developers can explore endpoints, try requests with live data, and see actual response shapes.

---

Rate Limiting

Protect your API from abuse by limiting request rates:

HTTP/1.1 200 OK
X-RateLimit-Limit: 1000
X-RateLimit-Remaining: 999
X-RateLimit-Reset: 1640995200

When clients exceed the limit:

HTTP/1.1 429 Too Many Requests
Retry-After: 3600

---

Caching Strategies

API Caching Strategies

Caching reduces load, improves latency, and decreases bandwidth costs. REST APIs can leverage HTTP caching primitives for significant gains.

HTTP Caching Primitives

Cache-Control Header

The Cache-Control header tells clients and intermediaries how to cache responses:

Cache-Control: public, max-age=300, stale-while-revalidate=60

Key directives:

• public — response can be cached by any cache (not just private)
• private — response is user-specific, only browser can cache
• max-age=N — cache for N seconds
• no-cache — always revalidate before using cached copy
• no-store — never cache (sensitive data)
• stale-while-revalidate=N — serve stale content while revalidating in background

ETags for Conditional Requests

ETags provide cache validation without re-downloading content:

# First request - server returns ETag
GET /users/123
HTTP/1.1 200 OK
ETag: "33a64df551425fcc55e4d42a148795d9f25f89d4"
Content-Type: application/json

{"id": 123, "name": "Alice"}

# Subsequent request - client sends If-None-Match
GET /users/123
If-None-Match: "33a64df551425fcc55e4d42a148795d9f25f89d4"
HTTP/1.1 304 Not Modified   # No body - use cached version

ETags should change when the resource changes. Use content hashing or version numbers.

HTTP Caching Hierarchy

Layer	Scope	Typical Duration	Use Case
Browser cache	User-specific	Minutes to days	Repeat visits, offline support
CDN	Shared	Minutes to hours	Static assets, API responses
Reverse proxy	Shared	Configurable	Origin protection, cost reduction
Application cache	Custom logic	Custom	Complex data, session tokens

Cache Invalidation

Cache Invalidation Patterns

Invalidation is harder than caching. Four patterns work well:

1. Time-based expiry — simplest, use max-age:

Cache-Control: public, max-age=3600  # Refresh after 1 hour

2. Event-driven invalidation — purge on updates:

# When user updates profile, invalidate related caches
DELETE /cache/users/123
DELETE /cache/users/123/profile
DELETE /cache/users/123/orders

3. Tag-based invalidation (surrogate keys) — tag responses, purge by tag:

# Response tagged with multiple keys
X-Surrogate-Key: user-123 order-456 product-789

# Purge all resources tagged with user-123
POST /purge
Surrogate-Key: user-123

4. Versioned URLs — change URL when content changes:

GET /users/123?v=2   # Cache bust by adding version

Caching for Different Request Types

Endpoint Type	Cache Strategy
Public list endpoints	Cache-Control: public, max-age=60
User-specific data	Cache-Control: private, max-age=300
Real-time data	Cache-Control: no-cache (always fresh)
Search results	Cache-Control: private, max-age=60 (often user-specific)
Health/check endpoints	Cache-Control: no-store (never cache)

---

Advanced Topics

When to Use REST

REST is the right choice when:

• You need a simple, well-understood API pattern
• HTTP caching benefits your use case
• You have multiple clients (web, mobile, third-party) consuming the same API
• Stateless request-response fits your data access patterns
• You want easy documentation and discoverability
• Standard HTTP infrastructure (CDNs, proxies, caches) helps
• You are building CRUD-oriented services

When Not to Use REST

REST may not be the best fit when:

• Clients need different data shapes (overfetching/underfetching issues)
• You need real-time updates (WebSockets, Server-Sent Events make more sense)
• Your queries are highly complex and deeply nested (GraphQL may fit better)
• You need batched operations that span multiple resources
• Mobile apps with limited bandwidth need precise data fetching
• Your API is tightly coupled to a single client needs

GraphQL vs REST: Trade-off Deep Dive

When choosing between REST and GraphQL, consider these trade-offs:

Factor	REST	GraphQL	Recommendation
Data fetching	Multiple endpoints; overfetching common	Single request; exact fields needed	GraphQL wins for complex UIs
Caching	HTTP caching (CDN, browser) works naturally	POST requests; requires custom caching layer	REST wins for simple caching needs
API evolution	Versioning adds complexity	Additive changes without versioning	GraphQL wins for rapidly evolving APIs
Error handling	Standard HTTP status codes	200 OK with errors in body; less explicit	REST wins for debuggability
Validation	Schema validation at API boundary	Type-safe schema; query validation at parse	GraphQL wins for developer experience
Monitoring	Endpoint-level metrics straightforward	Query-level metrics require additional tooling	REST wins for operational simplicity
Documentation	OpenAPI/Swagger integrates with many tools	Schema is the documentation; Self-documenting	GraphQL wins for discoverability
Client flexibility	Fixed response shapes per endpoint	Clients specify needed fields	GraphQL wins for heterogeneous clients
Batch operations	Multiple requests or custom batch endpoints	Single query with multiple operations	GraphQL wins
Real-time	WebSockets or SSE as separate concerns	Subscriptions built into schema	GraphQL wins for real-time

Hybrid Patterns

Many teams use both: REST for simple CRUD and authentication, GraphQL for complex data-fetching UI. This is a valid approach — don’t force uniformity where it doesn’t fit.

Webhook and Event Subscription Design

When REST APIs need to notify clients about events (rather than waiting for clients to poll), webhooks provide a push-based alternative. Designing webhook systems requires different considerations than request-response APIs.

Webhook Architecture

sequenceDiagram
    participant C as Client API
    participant S as Your API
    participant Q as Queue
    participant W as Webhook Handler

    S->>S: Resource changes
    S->>Q: Enqueue event
    Q->>W: Process event
    W->>C: POST webhook payload
    Note over C: Client processes event

Payload Design

Deliver structured, predictable payloads:

{
  "event": "user.created",
  "timestamp": "2026-03-22T10:30:00Z",
  "version": "2024-01",
  "data": {
    "id": "usr_abc123",
    "email": "alice@example.com",
    "created_at": "2026-03-22T10:29:58Z"
  },
  "metadata": {
    "correlation_id": "req_xyz789",
    "delivery_attempt": 1
  }
}

Delivery Guarantees

Webhooks are “at-least-once” by nature — network issues can cause duplicate deliveries. Design for that:

// Idempotent webhook handler
async function handleWebhook(payload, signature) {
  const eventId = payload.metadata?.event_id;

  // Check if already processed (idempotency key)
  const processed = await redis.get(`webhook:${eventId}`);
  if (processed) {
    return { status: "duplicate", acknowledged: true };
  }

  // Process the event
  await processEvent(payload);

  // Mark as processed with 7-day TTL
  await redis.setex(`webhook:${eventId}`, 604800, "processed");

  return { status: "processed", acknowledged: true };
}

Signature Verification

Always verify webhook signatures to prevent spoofing:

const crypto = require("crypto");

function verifyWebhookSignature(payload, signature, secret) {
  const expectedSignature = crypto
    .createHmac("sha256", secret)
    .update(payload)
    .digest("hex");

  // Use timing-safe comparison to prevent timing attacks
  return crypto.timingSafeEqual(
    Buffer.from(signature),
    Buffer.from(`sha256=${expectedSignature}`),
  );
}

Retry Strategy

When delivery fails, retry with exponential backoff:

Attempt	Delay
1	Immediate
2	5 minutes
3	30 minutes
4	2 hours
5	8 hours

After exhausting retries, log the failure and alert operators. Dead letter queues let you replay later.

Webhook Best Practices

• Send minimal required data — include enough to identify the resource, let clients fetch full data if needed
• Use stable event IDs — clients use them for deduplication
• Version your payloads — breaking changes require version bumps
• Provide test endpoint — let clients configure a test URL that echoes back payloads
• Include delivery metadata — timestamps, attempt numbers, correlation IDs for debugging

Trade-off Analysis

REST Trade-offs Summary

Designing REST APIs involves navigating several inherent trade-offs. Understanding these helps you make informed decisions for your specific use case.

Statelessness vs. Session State

Aspect	Stateless	Stateful (with sessions)
Scalability	Easy horizontal scaling — any server handles any request	Sessions must be shared or sticky; harder to scale
Complexity	Each request contains all context	Server manages session lifecycle
Reliability	Single request failure doesn’t corrupt session state	Session loss can corrupt client state
Performance	Higher latency — repeated auth/token validation	Lower latency — session context pre-loaded

Stateless REST APIs scale effortlessly but push complexity to clients. Stateful APIs reduce client complexity but introduce session management overhead.

Uniform Interface vs. Domain-Specific Optimisation

REST’s uniform interface (standard methods, status codes, link formats) enables generality — any client can consume any REST API. But it can feel constraining when your domain has unique access patterns:

• REST fits: CRUD-heavy resources, standard resource hierarchies, cacheable data
• REST strains: Complex multi-step workflows, domain-specific batch operations, real-time streams

Visibility vs. Efficiency

REST’s emphasis on explicit headers, standard methods, and cacheable responses makes intercepting proxies and monitoring easy. But this visibility comes at a cost — HTTP headers add overhead, and the request-response cycle can’t be optimised as tightly as binary protocols.

Versioning Strategies Trade-offs

Strategy	Pros	Cons
URL path (/v1/users)	Simple routing, easy to test, CDN-friendly	URL changes on every version bump
Header (Accept: vnd.api.v1+json)	Clean URLs, no URL pollution	Hard to test in browser, complex routing
Query param (?version=1)	Non-invasive, easy to add	Caching issues, often ignored by clients

Pagination Trade-offs

Type	Pros	Cons
Offset (?page=2&limit=20)	Simple, user can jump to any page	Inconsistent with live data (rows shift), slow on large tables
Cursor (?cursor=abc123)	Consistent under concurrent inserts, constant-time	Opaque, harder for users to navigate directly
Keyset (?since_id=123)	Very fast, great for “newer than X”	Limited to sorted-by-id use cases

---

Production Failure Scenarios

Failure	Impact	Mitigation
Missing pagination	Large datasets cause timeout or memory issues	Implement cursor or offset pagination; set reasonable limits
No rate limiting	API can be overwhelmed; DoS vulnerability	Implement rate limiting per client; return 429 with Retry-After
Inconsistent error responses	Clients cannot handle errors gracefully	Standardize error format; document all error codes
Version not implemented	Breaking changes affect existing clients	Version from day one; support multiple versions during transition
N+1 query problem	Database overwhelmed with queries	Use eager loading; batch related queries; optimize data fetching
Unbounded queries	Complex queries slow or crash database	Set query complexity limits; implement query timeouts
Missing authentication	Unauthorized access to sensitive data	Implement authentication on all endpoints; verify permissions
Insufficient validation	Invalid data corrupts database	Validate all input; use schema validation; return 400 for bad data

---

Observability Checklist

Metrics

• Request rate by endpoint, method, and client
• Response time distribution (p50, p95, p99) per endpoint
• Error rate by status code and endpoint
• Active connections or concurrent requests
• Authentication failures (attempted unauthorized access)
• Rate limit hits (429 responses)
• Payload size (request and response)
• Cache hit ratio (if using caching)

Logs

• All requests with request ID, method, path, status, duration
• Authentication and authorization failures with attempted credentials
• Validation errors with field-level details
• Database query times for slow queries (> 100ms)
• Rate limiting events with client identifier
• Error stack traces with correlation IDs

Alerts

• Error rate exceeds 1% for 5 minutes
• p99 latency exceeds 2 seconds
• Authentication failures spike (potential attack)
• Rate limit hits exceed normal threshold
• Unusual request size or pattern
• Database query times increasing
• Memory or CPU usage on API servers

---

Security Checklist

• Implement authentication on every protected endpoint
• Use authorization to verify permissions (not just authentication)
• Validate and sanitize all input data
• Use HTTPS for all API endpoints
• Set appropriate timeouts for all requests
• Implement rate limiting to prevent abuse
• Log security events (auth failures, suspicious patterns)
• Return minimal information in errors (do not leak internal details)
• Use secure, HttpOnly, SameSite cookies for sessions
• Implement CORS properly for cross-origin requests
• Protect against injection attacks (SQL, NoSQL)
• Validate Content-Type matches expected format
• Implement HEAD and OPTIONS method security
• Use API keys or JWT tokens, not passwords in URLs

---

Common Pitfalls / Anti-Patterns

Using Verbs in URLs

REST uses nouns for resources, not verbs for actions.

# WRONG - verbs in URLs
GET /api/getUsers
POST /api/createUser
POST /api/deleteUser

# CORRECT - nouns and HTTP methods
GET /api/users
POST /api/users
DELETE /api/users/123

Returning 200 for Errors

Always use appropriate status codes for errors.

# WRONG - 200 for error
HTTP/1.1 200 OK
{"error": "Not found"}

# CORRECT - proper status code
HTTP/1.1 404 Not Found
{"error": "User not found"}

Ignoring Pagination

Never return unbounded lists.

# WRONG - unbounded response
GET /api/users
# Could return millions of users

# CORRECT - paginated response
GET /api/users?page=1&limit=20
# Returns: {"data": [...], "pagination": {"page": 1, "limit": 20, "total": 1000}}

Not Implementing Versioning

APIs need to evolve without breaking clients.

# Version in URL path (most explicit)
GET /v1/users
GET /v2/users

# Version in header (cleaner URLs, harder to test)
GET /users
Accept: application/vnd.example.v2+json

Exposing Internal Details in Errors

Keep error responses informative but not leaky.

// WRONG - exposing internal details
{
  "error": "Database connection failed: mysql://user:pass@host:3306/db"
}

// CORRECT - safe error response
{
  "error": {
    "code": "INTERNAL_ERROR",
    "message": "An unexpected error occurred"
  }
}

---

Key Points

RESTful API design comes down to a few core principles. Use nouns for resource names, not verbs. Use plural names consistently. Apply HTTP methods correctly and use the right status codes. Paginate list endpoints. Format errors consistently. Version your API from the start. Secure endpoints with appropriate authentication. Implement rate limiting. Document everything with OpenAPI. Make incremental changes carefully.

---

Key Bullets

• REST uses nouns for resources (urls), not verbs (actions are HTTP methods)
• Use plural names consistently: /users not /user
• Use appropriate HTTP methods: GET (read), POST (create), PUT (replace), PATCH (modify), DELETE (remove)
• Return proper status codes: 2xx for success, 4xx for client errors, 5xx for server errors
• Implement pagination for list endpoints
• Standardize error response format across the API
• Version your API from the start to allow evolution
• Secure endpoints with authentication and authorization
• Implement rate limiting to protect against abuse
• Validate all input and return 400 for invalid data

Copy/Paste Checklist

# Test REST endpoint with curl
curl -X GET "https://api.example.com/users?page=1&limit=10" \
  -H "Authorization: Bearer eyJhbGciOiJIUzI1NiIs..." \
  -H "Accept: application/json"

# Create resource with POST
curl -X POST "https://api.example.com/users" \
  -H "Content-Type: application/json" \
  -d '{"name":"Alice","email":"alice@example.com"}'

# Update resource with PATCH
curl -X PATCH "https://api.example.com/users/123" \
  -H "Content-Type: application/json" \
  -d '{"email":"alice.new@example.com"}'

# Delete resource
curl -X DELETE "https://api.example.com/users/123" \
  -H "Authorization: Bearer ..."

# Check API version (if using header versioning)
curl -X GET "https://api.example.com/users" \
  -H "Accept: application/vnd.example.v2+json"

---

Quick Recap Checklist

Use this checklist when designing or reviewing a REST API:

Resource Design

• Resources use nouns, not verbs (/users not /getUsers)
• Resource names are plural consistently (/users not /user)
• Nested resources express relationships (/users/123/orders)
• Nesting depth is limited (max 2 levels typically)

HTTP Semantics

• GET is safe and idempotent (no side effects)
• POST creates new resources and returns 201 with Location header
• PUT replaces entire resources (idempotent)
• PATCH updates only specified fields (partial update)
• DELETE removes resources (idempotent)
• DELETE returns 204 on success, 404 if already gone

Response Status Codes

• 200 for successful GET, PUT, PATCH
• 201 for successful POST creating a resource
• 204 for successful DELETE (no body)
• 400 for malformed requests
• 401 for missing authentication
• 403 for authenticated but unauthorized
• 404 for resources that don’t exist
• 422 for validation errors
• 429 when rate limited

Request/Response

• Pagination on all list endpoints (?page=N&limit=N)
• Filtering and sorting via query parameters
• Consistent error response format with machine-readable codes
• Content-Type header specified for request bodies
• Location header on 201 responses

Security & Performance

• HTTPS on all endpoints
• Authentication on all protected endpoints
• Rate limiting implemented (X-RateLimit headers)
• Input validation on all endpoints
• Cache-Control appropriate for resource type
• ETag on mutable resources for conditional requests

Documentation

• OpenAPI spec defined before implementation
• All error codes documented
• Versioning strategy defined from day one

---

Interview Questions

Fundamentals

Design & Architecture

Advanced & Production

---

Further Reading

RESTful API design comes down to applying HTTP conventions consistently. Resources are nouns, actions are HTTP methods, and responses use standard status codes. Good naming, proper error handling, and thoughtful versioning create APIs that developers actually want to use.

For comparing REST with GraphQL, see the GraphQL vs REST post. For API versioning details, see the API Versioning Strategies post.

---

Conclusion

REST remains the foundation of modern web API design. The principles established by Fielding — resources, uniform interface, statelessness, and hypermedia — provide a durable framework that scales from simple CRUD services to complex distributed systems. Success with REST comes from disciplined application of HTTP conventions: meaningful status codes, consistent resource naming, proper error formatting, and thoughtful versioning strategy from the start.

Design decisions made at the API boundary ripple through every client and service that depends on it. Investing in clean resource models, idempotent operations, and comprehensive error handling pays dividends across the lifetime of your API. Use the checklists and trade-off analysis in this guide as a starting point, then adapt to your specific domain constraints.