REST API Design Principles: Best Practices for 2026

What Makes a RESTful API Well-Designed?

REST (Representational State Transfer) is an architectural style for building networked applications. A well-designed REST API is predictable, consistent, and intuitive for developers to consume. It follows HTTP semantics faithfully, uses clear resource-based URLs, and returns meaningful status codes with structured error messages.

Poor API design is one of the biggest sources of developer frustration. APIs that use inconsistent naming, return wrong status codes, or lack pagination force consumers to write brittle, workaround-heavy code. In contrast, APIs from companies like Stripe, GitHub, and Twilio are praised because they follow REST conventions rigorously, making integration straightforward even without reading every page of documentation.

This guide covers the core principles that separate excellent APIs from mediocre ones. Whether you are building a public API or an internal microservice, these patterns will make your endpoints easier to use, maintain, and scale.

HTTP Methods: Using the Right Verb for Each Operation

HTTP methods (also called verbs) define the type of operation being performed on a resource. Using the correct method is not just convention -- it determines caching behavior, idempotency guarantees, and whether intermediaries like proxies and CDNs can safely optimize requests.

A common mistake is using POST for everything. This prevents HTTP caches from working, breaks browser back-button behavior, and makes it impossible for clients to safely retry failed requests. Always match the method to the operation semantics.

# Good: Using correct HTTP methods
GET    /api/v1/users          # List users
GET    /api/v1/users/42       # Get user 42
POST   /api/v1/users          # Create a new user
PUT    /api/v1/users/42       # Replace user 42 entirely
PATCH  /api/v1/users/42       # Update specific fields of user 42
DELETE /api/v1/users/42       # Delete user 42

# Bad: Using POST for everything
POST   /api/v1/getUsers       # Should be GET
POST   /api/v1/deleteUser     # Should be DELETE
POST   /api/v1/updateUser     # Should be PUT or PATCH

Resource Naming: Building Intuitive URL Structures

Resource naming is the foundation of API usability. A well-named API reads like a sentence: GET /users/42/orders clearly means "get the orders belonging to user 42." Poor naming forces developers to check documentation for every single endpoint.

Core Naming Rules

1. Use nouns, not verbs -- Resources are things, not actions. Use /invoices not /getInvoices. The HTTP method provides the verb.
2. Use plural nouns for collections -- /users not /user, even when fetching a single resource (/users/42).
3. Use kebab-case for multi-word resources -- /tax-calculations not /taxCalculations or /tax_calculations. URLs are case-insensitive by convention.
4. Nest resources to show relationships -- /users/42/orders/7 is clearer than /orders/7?userId=42 for parent-child relationships.
5. Limit nesting depth to two levels -- /users/42/orders/7/items is acceptable, but deeper nesting becomes unwieldy. Use query parameters or separate endpoints instead.

// Real-world resource hierarchy example
// A tax calculation API (like levyio.com) might structure routes as:

GET  /api/v1/tax-calculations                  // List all calculations
POST /api/v1/tax-calculations                  // Create a new calculation
GET  /api/v1/tax-calculations/2026             // Get 2026 calculation
GET  /api/v1/tax-calculations/2026/deductions  // List deductions for 2026
POST /api/v1/tax-calculations/2026/deductions  // Add a deduction

// Filtering via query parameters (not URL paths)
GET  /api/v1/tax-calculations?year=2026&status=filed
GET  /api/v1/tax-calculations?filing_type=married_joint

When designing URL structures, keep in mind that URLs are also data. They get logged, bookmarked, shared in Slack messages, and pasted into bug reports. A readable URL makes everyone's life easier, from the frontend developer debugging a network tab to the support engineer reading a customer's error log.

API Versioning Strategies

Breaking changes are inevitable as your API evolves. Versioning lets you introduce changes without breaking existing integrations. There are three common approaches, each with trade-offs.

1. URL Path Versioning (Recommended)

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

This is the most explicit and widely adopted approach, used by Stripe, GitHub, and Google. The version is immediately visible in every request, making debugging and logging straightforward.

2. Header Versioning

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

Keeps URLs clean but hides the version, making it harder to debug from logs or browser dev tools.

3. Query Parameter Versioning

GET /api/users/42?version=2

Easy to implement but can conflict with other query parameters and is easy to forget. Generally not recommended for production APIs.

Error Handling: Returning Useful Error Responses

Error responses are arguably more important than success responses. When something goes wrong, developers need enough information to understand what happened, why it happened, and how to fix it. A bare 500 Internal Server Error with no body is the worst possible developer experience.

Use the correct HTTP status code and include a structured error body. You can validate and format your API error responses using our JSON Formatter to ensure they are well-structured before documenting them.

// A well-structured error response
// HTTP 422 Unprocessable Entity
{
  "error": {
    "code": "VALIDATION_ERROR",
    "message": "The request body contains invalid fields.",
    "details": [
      {
        "field": "email",
        "message": "Must be a valid email address.",
        "rejected_value": "not-an-email"
      },
      {
        "field": "age",
        "message": "Must be a positive integer.",
        "rejected_value": -5
      }
    ],
    "request_id": "req_abc123",
    "documentation_url": "https://api.example.com/docs/errors#validation"
  }
}

Essential HTTP Status Codes for APIs

Pagination: Handling Large Collections Efficiently

Any endpoint that returns a list of resources must support pagination. Without it, a single query could return millions of records, overwhelming both server memory and client bandwidth. There are two dominant pagination strategies, and choosing the right one depends on your data characteristics.

Offset-Based Pagination

The simplest approach. The client specifies which page to retrieve and how many items per page. Easy to implement but suffers from inconsistency when records are inserted or deleted between requests.

GET /api/v1/users?page=3&per_page=25

// Response
{
  "data": [ ... ],
  "pagination": {
    "page": 3,
    "per_page": 25,
    "total_items": 1250,
    "total_pages": 50,
    "has_next": true,
    "has_prev": true
  }
}

Cursor-Based Pagination (Recommended for Large Datasets)

Uses an opaque cursor (typically a Base64-encoded identifier) to mark the position in the dataset. More performant at scale and immune to the "shifting window" problem of offset pagination.

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

// Response
{
  "data": [ ... ],
  "pagination": {
    "next_cursor": "eyJpZCI6MTI1fQ==",
    "has_more": true
  }
}

// The cursor is opaque to the client -- they just pass it back
GET /api/v1/users?limit=25&cursor=eyJpZCI6MTI1fQ==

HATEOAS: Hypermedia-Driven APIs

HATEOAS (Hypermedia as the Engine of Application State) is the most mature level of REST API design. Instead of hardcoding URL patterns into clients, the API response includes links that tell the client what actions are available and where to find related resources.

// A HATEOAS-compliant order response
{
  "id": 42,
  "status": "pending",
  "total": 99.99,
  "created_at": "2026-03-07T10:30:00Z",
  "_links": {
    "self": { "href": "/api/v1/orders/42" },
    "cancel": { "href": "/api/v1/orders/42", "method": "DELETE" },
    "pay": { "href": "/api/v1/orders/42/payments", "method": "POST" },
    "customer": { "href": "/api/v1/users/7" },
    "items": { "href": "/api/v1/orders/42/items" }
  }
}

// After payment, the "pay" link disappears and "refund" appears
{
  "id": 42,
  "status": "paid",
  "total": 99.99,
  "_links": {
    "self": { "href": "/api/v1/orders/42" },
    "refund": { "href": "/api/v1/orders/42/refunds", "method": "POST" },
    "receipt": { "href": "/api/v1/orders/42/receipt" }
  }
}

While full HATEOAS adoption remains rare in practice, even partial adoption (like including _links.self and pagination URLs) dramatically improves API discoverability and reduces the chance of clients constructing invalid URLs.

Request and Response Best Practices

Beyond the structural principles above, several practical conventions make APIs more robust and developer-friendly. These small details compound to create a polished integration experience.

Use Consistent JSON Conventions

Pick one naming convention for JSON keys and stick with it. camelCase is standard for JavaScript APIs, snake_case for Ruby and Python APIs. Never mix conventions within the same API. Use our JSON Formatter to verify your response structure is consistent during development.

Include Request IDs

// Every response should include a unique request ID
// This enables end-to-end debugging across services

HTTP/1.1 200 OK
X-Request-Id: req_a1b2c3d4e5f6
Content-Type: application/json

{
  "data": { ... },
  "meta": {
    "request_id": "req_a1b2c3d4e5f6"
  }
}

Support Filtering and Sorting

// Filtering: use query parameters with clear field names
GET /api/v1/products?category=electronics&price_min=50&price_max=200

// Sorting: use a sort parameter with direction prefix
GET /api/v1/products?sort=-created_at      // descending
GET /api/v1/products?sort=price            // ascending
GET /api/v1/products?sort=-price,name      // multi-field

// Field selection: let clients request only needed fields
GET /api/v1/users/42?fields=id,name,email

URL Encoding in Query Parameters

When passing special characters in query parameters, they must be properly URL-encoded. Spaces become %20, ampersands become %26, and so on. Use our URL Encoder to test encoding and decoding of complex query strings during API development.

Rate Limiting and Security

Every public API needs rate limiting to protect against abuse and ensure fair access. Return rate limit information in response headers so clients can implement backoff strategies without guessing.

HTTP/1.1 200 OK
X-RateLimit-Limit: 1000
X-RateLimit-Remaining: 847
X-RateLimit-Reset: 1709827200

// When rate limited:
HTTP/1.1 429 Too Many Requests
Retry-After: 30
{
  "error": {
    "code": "RATE_LIMIT_EXCEEDED",
    "message": "You have exceeded the rate limit of 1000 requests per hour.",
    "retry_after": 30
  }
}

For real-world API integrations -- such as connecting to tax calculation services or financial data providers -- rate limiting is especially critical because each request may involve expensive computations or third-party lookups. Design your rate limits to reflect the actual cost of each operation.

Related Articles