REST API Guidelines in 2026: A Practical Guide for Modern Developers

REST APIs have been the backbone of web services for over two decades, and in 2026 they remain the dominant approach for building web-facing APIs. Yet despite REST’s maturity and widespread adoption, many APIs still violate fundamental guidelines that make them difficult to use, maintain, and scale. This guide consolidates the most important REST API guidelines into a practical reference that developers can apply immediately to their work.

Understanding REST in the Modern Context

What REST Actually Means

Representational State Transfer, or REST, was introduced by Roy Fielding in his 2000 doctoral dissertation as an architectural style for distributed hypermedia systems. REST is not a protocol or a standard; it is a set of constraints that, when applied to an API design, produce desirable properties like scalability, simplicity, and reliability.

The core REST constraints are statelessness, client-server separation, cacheability, uniform interface, and layered system architecture. Understanding why these constraints exist helps you make better design decisions. Statelessness enables horizontal scaling because any server can handle any request. Cacheability improves performance by allowing responses to be stored and reused. The uniform interface simplifies the overall system by enforcing a consistent contract between components.

Many APIs that claim to be RESTful violate these constraints in ways that undermine their benefits. An API that requires authentication state maintained on the server is not truly RESTful. An API that returns different representations to different clients without negotiation breaks the uniform interface constraint. Knowing what REST actually requires helps you distinguish genuine REST APIs from those that merely use HTTP.

The Maturity Model: Richardson’s API Maturity

Leonard Richardson proposed a useful model for understanding API maturity that breaks down REST compliance into levels. Understanding this model helps you decide where your API should fall on the spectrum.

Level 0 is the swampland of API design: a single endpoint that handles all operations, typically using a single HTTP method. This is how XML-RPC and early SOAP APIs worked, and many “REST APIs” that developers complain about are actually operating at this level.

Level 1 introduces resources. Operations are distributed across multiple endpoints, each representing a different entity or concept. However, all operations still use a single HTTP method, usually POST.

Level 2 adds HTTP verbs. Different operations use different HTTP methods appropriately: GET for retrieval, POST for creation, PUT for replacement, DELETE for removal. This level also introduces proper use of HTTP status codes to communicate outcomes.

Level 3 is the highest level of REST maturity, adding hypermedia controls. Responses include links that clients can follow to discover available actions. This enables APIs that are self-documenting and allows clients to interact with the API through discovered links rather than hardcoded URLs.

Most production APIs today operate at Level 2, which provides most of REST’s benefits without the complexity of full hypermedia implementation. Understanding where your API falls helps you make conscious decisions about which level to target.

URL Structure and Naming

Building Logical URL Hierarchies

The structure of your URLs communicates the structure of your data model. Well-designed URLs make the API intuitive to navigate and understand. Poorly designed URLs create confusion that ripples through every client implementation.

Use nouns to represent resources. Your URL path should read like a collection of things: /users, /products, /invoices. Avoid verbs in URLs: /getUser or /createProduct violate REST conventions and create inconsistent naming patterns. The HTTP method provides the verb; the URL provides the noun.

Organize URLs hierarchically to represent relationships. When a resource belongs to another resource, nest it logically: /companies/456/employees clearly indicates employees belonging to a specific company. However, avoid nesting more than two levels deep. Three-level nesting like /companies/456/departments/123/employees/789 becomes difficult to work with and hard to maintain.

Use IDs for navigation rather than human-readable slugs when appropriate. Both /users/123 and /users/john-doe are valid approaches. IDs are more stable if names can change and avoid encoding issues with special characters. Human-readable slugs are more discoverable and produce prettier URLs. Many APIs use a hybrid approach: /users/123 for machine clients and /users/john-doe for human-facing applications.

Versioning in URLs

API versioning is essential for managing evolution without breaking existing clients. The most common approach, and the one most developers expect, is version numbers in the URL path: /api/v1/users, /api/v2/users.

Start with v1 even if you have no plans for versioning. Adding v1 to your URLs from the beginning establishes the pattern before you need it and makes the first migration to v2 less dramatic. Without v1, going from unversioned URLs to /v1/ feels like a breaking change even though it’s not.

Use semantic versioning principles for your API version numbers. A new version number indicates significant changes, not every modification. Increment the major version for breaking changes. Minor version increments can indicate additions that don’t break existing functionality, though many teams prefer to keep version increments simple and only increment on breaking changes.

Consider maintaining only two versions simultaneously. Supporting multiple major versions doubles your testing surface, documentation burden, and maintenance costs. When you release version 3, commit to deprecating version 1 and give developers ample time to migrate. Communicate deprecation clearly and provide migration guides.

HTTP Methods and Their Usage

GET: Retrieving Resources

GET requests are the workhorses of REST APIs. They retrieve resources without modifying server state, making them safe and idempotent. These properties are not just theoretical; they are guarantees that clients and caching infrastructure rely upon.

Never modify data in response to a GET request. This rule seems obvious, but it can be violated in subtle ways. Logging requests, updating last-accessed timestamps, and tracking view counts are all modifications that should not occur on GET requests. If you need to record that a resource was accessed, do so asynchronously or through a separate mechanism.

Return appropriate status codes for GET responses. 200 OK for successful retrieval. 404 Not Found when the resource doesn’t exist. 301 Moved Permanently or 302 Found when the resource has moved to a different URL. Never return 200 OK with an empty body for a resource that doesn’t exist; this makes it impossible for clients to distinguish between “no data” and “no such resource.”

Support filtering, sorting, and pagination. Single endpoints rarely return all resources of a type. Use query parameters to allow clients to narrow results: /orders?status=shipped, /products?category=electronics. Support sorting: /products?sort=price,desc. Implement pagination: /products?page=2&per_page=50.

POST: Creating Resources

POST requests create new resources. The server assigns the resource identifier, and the response includes the created resource or a reference to it. POST is not idempotent: submitting the same POST request multiple times creates multiple resources.

Return 201 Created with a Location header for successful creation. The Location header should point to the newly created resource. Include the complete resource representation in the response body so clients don’t need to make a follow-up request.

Handle duplicate creation requests gracefully. If a POST request creates a resource with a unique constraint violation, return 409 Conflict with information about the existing resource. Some APIs prefer to treat duplicate creation as an update operation, but this conflates creation and modification and can lead to unexpected behavior.

Validate input thoroughly before creating resources. Return 400 Bad Request with detailed validation errors when input data doesn’t meet requirements. Don’t create resources with partial data and then return errors about missing fields; validate everything upfront.

PUT: Replacing Resources Completely

PUT requests create or completely replace a resource at a specified URL. PUT is idempotent: submitting the same PUT request multiple times produces the same result. Use PUT when clients provide the complete resource representation.

Return 200 OK or 204 No Content on successful replacement. If returning a body, include the updated resource representation. If returning 204, ensure the update succeeded without needing to return data.

Return 404 Not Found when the resource doesn’t exist. Some APIs create resources on PUT, but this behavior confuses clients about what PUT does. If PUT should only update existing resources, return 404 when the resource isn’t found.

Require complete resource representations. PUT should receive the full resource, not just the fields to update. If clients need partial updates, they should use PATCH instead.

PATCH: Modifying Resources Partially

PATCH requests partially update an existing resource. Unlike PUT’s complete replacement semantics, PATCH modifies specific fields while leaving others unchanged. PATCH is less semantic than PUT and is appropriate when clients want to update individual fields.

Use a clear patch format. JSON Merge Patch (RFC 7396) is simple: send the fields to update with their new values, omit fields to leave unchanged, and explicitly set fields to null to clear them. JSON Patch (RFC 6902) is more powerful, allowing operations like move, copy, and test. Choose one format and document it clearly.

Return the updated resource or 204 No Content. After a successful PATCH, return the modified resource or nothing, depending on your API’s pattern. Return 404 if the resource doesn’t exist, and 400 if the patch format is invalid.

DELETE: Removing Resources

DELETE requests remove resources. DELETE should be idempotent: deleting an already-deleted resource should return success, not an error.

Return 204 No Content for successful deletion. The deletion succeeded; there’s no need to return data. Some APIs return 200 with the deleted resource, which is also acceptable.

Return 404 Not Found for resources that never existed. If the resource was already deleted, return 204 to maintain idempotency. If you’re unsure whether the resource existed, returning 404 is reasonable, though it breaks client retry logic.

Consider soft deletes for important resources. Hard deletes permanently remove data, which can cause problems with auditing, recovery, and data integrity. Many resources benefit from a soft delete pattern where a deleted_at timestamp marks the resource as inactive rather than physically removing it.

Status Codes: The Complete Guide

Success Codes (2xx)

The 2xx status codes indicate that the server received and processed the request successfully. Understanding when to use each code matters for building predictable APIs.

200 OK is the default success code. Use it for successful GET, PUT, PATCH, and DELETE requests that return a body. If the request was successful and there’s nothing meaningful to return, 204 No Content is more appropriate.

201 Created is the correct code for POST requests that create new resources. Always accompany it with a Location header pointing to the new resource and ideally with the resource representation in the body.

202 Accepted indicates that a request was received and will be processed asynchronously. Use this for operations that take time to complete, where the client shouldn’t wait for completion. Include information about how to check the operation’s status.

204 No Content is for successful operations that return no body. This is the preferred response for successful DELETE operations and for PUT/PATCH operations where returning the updated resource doesn’t provide value.

Client Error Codes (4xx)

The 4xx codes indicate problems with the client’s request. The request should not be retried without modification.

400 Bad Request means the server couldn’t understand the request due to malformed syntax, invalid structure, or semantic errors. Always include a response body that explains what went wrong.

401 Unauthorized means the request lacks valid authentication credentials. The response should include information about how to authenticate. Note that “unauthorized” is technically incorrect terminology; “unauthenticated” would be more accurate, but 401 is the standard.

403 Forbidden means the server understood the request and has the credentials, but the client doesn’t have permission. Unlike 401, this response should not reveal whether the resource exists. Return 403 for resources the client genuinely cannot access.

404 Not Found means the requested resource doesn’t exist. For security, avoid revealing whether a resource exists when the client doesn’t have access to it; return 404 instead of 403 in those cases.

405 Method Not Allowed means the HTTP method isn’t supported for this endpoint. Include an Allow header listing the supported methods.

409 Conflict means the request conflicts with current server state. Use it for duplicate creation attempts, optimistic concurrency conflicts, and state transition errors.

422 Unprocessable Entity means the request is syntactically correct but semantically invalid. Use it for validation errors when the request body is well-formed JSON but contains invalid data.

429 Too Many Requests indicates rate limiting. Include a Retry-After header telling the client when to retry.

Server Error Codes (5xx)

The 5xx codes indicate that the server failed to fulfill a valid request. These errors should be rare, and when they occur, they should be thoroughly logged.

500 Internal Server Error is the generic server error. Never expose internal error details to clients. Return a reference identifier that correlates with your logs so developers can get help.

502 Bad Gateway and 503 Service Unavailable indicate infrastructure problems. Return these appropriately when your servers or dependencies are down. Include Retry-After headers when appropriate.

Pagination and Filtering

Cursor-Based Pagination

Cursor-based pagination has become the preferred approach for most APIs because it provides stable, consistent pagination even when data changes during iteration. Unlike offset pagination, cursor pagination doesn’t produce duplicate or skipped results when data is inserted or deleted during pagination.

Cursors are typically opaque strings that encode the position in the result set. Servers can use various strategies to generate cursors: encoding the last item’s ID and sort field, encoding an absolute position, or using a base64-encoded pointer to a server-side iterator.

To implement cursor pagination, accept a cursor parameter that specifies where to start. Return a next_cursor in the response that clients use for the next page. Include a has_more boolean or explicit next URL to indicate whether more results exist.

GET /messages?cursor=abc123

{
  "data": [...],
  "pagination": {
    "next_cursor": "def456",
    "has_more": true
  }
}

Offset-Based Pagination

Offset pagination remains useful for APIs where users navigate to specific pages and need to jump around rather than iterate sequentially. News feeds, search results, and category listings often benefit from offset pagination.

Accept page and per_page parameters, where page defaults to 1 and per_page has a reasonable default (20-100 items) and a maximum limit. Return total count and page information.

GET /products?page=3&per_page=50

{
  "data": [...],
  "pagination": {
    "page": 3,
    "per_page": 50,
    "total": 1247,
    "total_pages": 25
  }
}

Filtering and Search

Well-designed filtering makes APIs flexible without requiring an explosion of specialized endpoints. Use query parameters that match resource fields: /orders?status=pending. Support multiple values: /orders?status=pending,processing. Support ranges: /orders?created_after=2026-01-01&created_before=2026-01-31.

For full-text search, use a dedicated q or search parameter: /products?search=wireless+headphones. For complex filtering, consider a filter expression language, though simpler single-field filters cover most use cases.

Authentication Patterns

API Keys for Server-to-Server Communication

API keys are the simplest authentication mechanism. The client includes a key in each request, and the server validates it. API keys work well for server-to-server communication where the key can be kept confidential.

Pass API keys in the Authorization header using the ApiKey scheme: Authorization: ApiKey your-api-key-here. Avoid passing keys in URL parameters because keys in URLs end up in server logs, browser history, and other places they shouldn’t be.

Implement key rotation without downtime by supporting two active keys simultaneously during a transition period. Allow clients to generate new keys before revoking old ones.

Bearer Tokens and OAuth 2.0

Bearer tokens are the standard for APIs accessed by user-facing applications. The most common format is JWT (JSON Web Tokens), which encode claims in a compact, self-contained format.

For APIs where clients act on behalf of users, OAuth 2.0 provides the authorization framework. Users grant specific permissions to applications, and applications receive tokens that grant those permissions. OAuth 2.0 handles the complexity of credential handling and permission management so you don’t have to.

When implementing OAuth or bearer tokens, keep token lifetimes short. Long-lived tokens are security risks. Implement refresh token flows that allow clients to obtain new access tokens without requiring the user to re-authenticate.

Keeping APIs Secure

Security is not optional. Every API that handles sensitive data must implement appropriate protection mechanisms.

Always use HTTPS. Plain HTTP exposes credentials and data to network eavesdropping. Certificate management has become simple with Let’s Encrypt and automated renewal, so there’s no excuse for plain HTTP in 2026.

Validate all input at every endpoint. Never trust client data. Check data types, ranges, formats, and sizes. Reject clearly invalid input with 400 Bad Request.

Implement rate limiting to prevent abuse. Without rate limiting, your API can be overwhelmed by malicious or accidental excessive usage. Start with generous limits and tighten them based on observed patterns.

Log access for auditing but never log credentials, tokens, or sensitive personal data. Logs are invaluable for debugging and security analysis, but they become liability if they contain sensitive data that is subsequently exposed.

Error Response Design

The Anatomy of a Good Error Response

Every error response should include the information developers need to understand and respond to the error. A consistent error structure across your API reduces cognitive load and makes your API more pleasant to work with.

Include a machine-readable error code that clients can switch on: "error_code": "resource_not_found". Include a human-readable message that explains what went wrong: "message": "The requested user does not exist.". Include detailed information when available: "details": {"field": "user_id", "value": "nonexistent-id"}. Include a reference identifier that correlates with your logs: "reference_id": "req_abc123".

{
  "error": {
    "code": "validation_error",
    "message": "Request validation failed.",
    "details": [
      {
        "field": "email",
        "message": "Must be a valid email address.",
        "value": "not-an-email"
      }
    ],
    "reference_id": "req_abc123xyz"
  }
}

Handling Validation Errors

Validation errors deserve special attention because they are the most common error developers encounter when integrating with your API. Clear validation errors dramatically reduce integration time.

Validate input before executing business logic. Don’t partially process requests and then fail. Validate everything, collect all errors, and return them together rather than failing on the first error. This “fail fast, fail completely” approach saves developers from fixing one error only to discover another.

Be specific about which field failed and why. “Invalid input” is not helpful. “The ‘email’ field must be a valid email address” tells developers exactly what to fix. For complex validations, explain the constraint: “The ‘start_date’ must be before the ‘end_date’.”

Distinguish between missing required fields and invalid optional fields. Missing required fields should say so explicitly. Invalid format on an optional field should explain the expected format.

Conclusion

These REST API guidelines represent accumulated wisdom from years of building and consuming APIs. Applied consistently, they produce APIs that are intuitive to use, straightforward to maintain, and resilient to change. Remember that an API is a contract with its consumers: invest in making that contract clear, consistent, and thoughtful. Your developers will thank you, and your future self will appreciate the maintainability.