REST API Design Rulebook

1. REST APIs leverage HTTP's full capabilities for scalable web communication

REST tells us how the Web achieves its great scale.

Architectural constraints enable scalability. REST (Representational State Transfer) is the architectural style of the World Wide Web, designed to enable massive scalability. It achieves this through key constraints:

• Client-server separation of concerns
• Stateless interactions
• Uniform interface (including resource identification, manipulation through representations, self-descriptive messages, and hypermedia controls)
• Layered system allowing intermediaries
• Caching to reduce latency
• Optional code-on-demand for client extensibility

These constraints work together to create a distributed system capable of handling enormous numbers of interactions while remaining flexible and performant.

2. URIs should uniquely identify resources without revealing implementation details

Every character within a URI counts toward a resource's unique identity.

Design clear, hierarchical URIs. URIs (Uniform Resource Identifiers) are the cornerstone of REST APIs, uniquely identifying each resource. Best practices for URI design include:

• Use forward slashes to indicate hierarchical relationships
• Prefer lowercase letters
• Use hyphens to improve readability
• Avoid file extensions
• Use plural nouns for collections
• Use singular nouns for specific resources
• Employ consistent naming conventions across the API

Well-designed URIs should be intuitive and self-describing, allowing developers to understand the resource structure without needing extensive documentation. However, clients should treat URIs as opaque identifiers and not attempt to parse meaning from them directly.

3. HTTP methods define standard interactions with resources

A REST API must not compromise its design by misusing HTTP's request methods in an effort to accommodate clients with limited HTTP vocabulary.

Use HTTP methods consistently. The standard HTTP methods provide a uniform interface for interacting with resources:

• GET: Retrieve a resource representation
• POST: Create a new resource in a collection or execute a controller
• PUT: Update an existing resource or create a new resource in a store
• DELETE: Remove a resource
• HEAD: Retrieve metadata about a resource
• OPTIONS: Discover available interactions for a resource

Each method has specific semantics and expected behavior. For example, GET should be safe and idempotent, while POST may have side effects. Consistently applying these methods across your API design enhances predictability and interoperability.

4. Metadata in HTTP headers enhances API functionality and performance

Caching is one of the most useful features built on top of HTTP.

Leverage HTTP headers for metadata. HTTP headers provide a wealth of functionality for REST APIs:

• Content-Type: Specifies the media type of the request or response body
• ETag: Enables efficient caching and conditional requests
• Cache-Control: Directs caching behavior for improved performance
• Authorization: Supports various authentication schemes
• Accept: Allows content negotiation for different representations

Proper use of headers can significantly improve API performance, security, and flexibility. For example, effective use of caching headers can reduce server load and improve response times, while authentication headers enable secure access control.

5. Resource representations should use consistent formats and hypermedia controls

REST API clients should be encouraged to rely on the self-descriptive features of a REST API.

Design self-describing representations. Resource representations should be consistent and self-describing:

• Use standard formats like JSON or XML
• Include hypermedia controls (links) to guide clients through available actions
• Employ consistent structures for common elements like errors
• Use descriptive field names and appropriate data types
• Include metadata about the representation (e.g., schema information)

Hypermedia controls are particularly important, as they allow the API to guide clients through the application state. This enables looser coupling between clients and servers, improving the API's evolvability.

6. Versioning, security, and composition strategies improve API flexibility

OAuth is an HTTP-based authorization protocol that enables the protection of resources.

Design for evolution and security. Key strategies for flexible and secure APIs include:

• Versioning: Use schema versioning rather than URI versioning
• Security: Implement OAuth or API management solutions for access control
• Partial responses: Allow clients to request only needed fields
• Embedded resources: Enable clients to retrieve related resources in a single request
• Error handling: Provide consistent, informative error responses

These strategies allow APIs to evolve over time without breaking existing clients, while also providing the security and efficiency features required by modern applications.

7. JavaScript clients require special considerations for cross-origin requests

CORS is an alternative to JSONP that supports all request methods.

Enable cross-origin access. Browser security restrictions can pose challenges for JavaScript clients accessing APIs from different domains. Two main approaches address this:

• JSONP (JSON with Padding): Allows read-only access by exploiting script tag behavior
• CORS (Cross-Origin Resource Sharing): Provides full read/write access with browser support

CORS is the more robust and standardized approach, supporting all HTTP methods. By implementing CORS, APIs can securely allow access from JavaScript applications hosted on different domains, enabling rich web applications and mashups.

Last updated: September 5, 2024