Representational State Transfer (REST) and Design Principles
REST is an architectural style designed for constructing distributed systems using hypermedia. It is protocol-independent and not inherently associated with HTTP, although most REST API implementations commonly utilize HTTP as the application protocol. Many developers commonly link REST with HTTP, leading to potential confusion. To avoid any perplexity, it’s important to note that REST is not exclusively bound to HTTP; any transfer protocol can be employed to establish a RESTful API. In essence, RESTful services simply adhere to the principles of a REST architecture, irrespective of the underlying transfer protocol.
This guide concentrates on crafting REST APIs specifically for HTTP. One key benefit of REST over HTTP lies in its adherence to open standards, avoiding constraints on the API or client application implementation. For instance, a REST web service developed in ASP.NET can interact seamlessly with client applications using any language or toolset capable of crafting HTTP requests and interpreting HTTP responses.
There are six architectural constraints for any RESTful service:
- Uniform Interface
- Stateless
- Cacheable
- Client-Server
- Layered System
- Code on Demand — Optional
Uniform Interface
It represents a fundamental constraint distinguishing between a REST API and a Non-REST API. This principal advocates for a consistent method of interacting with a particular server, regardless of the device or type of application (website, mobile app).
The Uniform Interface encompasses four guiding principles:
Resource-Centric:
REST APIs are structured around resources, which encompass any object, data, or service accessible to the client. A URI (Uniform Resource Identifier) uniquely identifies each resource. For instance, the URI for a specific customer order could be:
https://adventure-works.com/orders/1Manipulation of Resources Through Representations:
Clients possess a representation of the resource, containing sufficient information for modifying or deleting it on the server, granted the necessary permissions. Many web APIs utilize JSON as the exchange format. As an example, a GET request to the URI might yield the following response body:
{"orderId":1,"orderValue":99.90,"productId":1,"quantity":1}Self-descriptive Messages:
Every message incorporates adequate information to elucidate its processing, facilitating straightforward analysis by the server. REST APIs adhere to a uniform interface, decoupling client, and service implementations. In the case of REST APIs based on HTTP, the uniform interface employs standard HTTP verbs like GET, POST, PUT, PATCH, and DELETE for resource operations.
Hypermedia as the Engine of Application State (HATEOAS):
REST APIs rely on hypermedia links within the representation to navigate application state. For instance, consider a JSON representation of an order with embedded links for obtaining or updating the associated customer:
{
"orderID":3,
"productID":2,
"quantity":4,
"orderValue":16.60,
"links": [
{"rel":"product","href":"https://adventure-works.com/customers/3", "action":"GET" },
{"rel":"product","href":"https://adventure-works.com/customers/3", "action":"PUT" }
]
}Stateless
REST APIs adhere to a stateless request model, emphasizing that HTTP requests must be self-contained and independently processable in any sequence. The absence of transient state information retention between requests enhances scalability by removing the need for client-server affinity, allowing any server to manage requests from any client. Although scalability may be influenced by factors such as backend data store limitations, this constraint facilitates a highly scalable architecture.
Cacheable
Responses from REST APIs must specify whether they are cacheable and the duration for which clients can cache them. Effective caching can significantly reduce client-server interactions, enhancing availability and performance. However, there is a trade-off, as cached data may become stale, potentially presenting outdated information to users.
Client-Server
A fundamental tenet of REST architecture is the client-server model, emphasizing a clear separation of concerns. Clients, responsible for requesting resources, remain unconcerned with data storage, while servers, holding the resources, are agnostic to user interfaces or states. This decoupling allows independent evolution of clients and servers, with clients unaware of server business logic and servers unacquainted with frontend UI details.
Layered system
RESTful application architectures are structured with multiple layers, each oblivious to layers beyond its immediate scope. Intermediate servers, positioned between clients and end servers, can enhance system availability through load balancing and shared caches.
Code on demand
Code on demand is an optional feature, allowing servers to deliver executable code to clients. Examples of code on demand include compiled components like Java Servlets and server-side scripts such as JavaScript. This feature provides flexibility but is not a mandatory aspect of REST architecture.
It’s essential to distinguish between a RESTful API and an HTTP API. A RESTful API strictly follows all the constraints outlined in its “format” documentation, as specified in Roy Fielding’s dissertation. On the other hand, an HTTP API is any API utilizing HTTP as its transfer protocol. This implies that even SOAP can be categorized as an HTTP API if it utilizes HTTP for transport. However, most HTTP APIs tend to maximize the capabilities and infrastructure of HTTP, making them closely aligned with the principles of a truly RESTful API. The progression towards a genuinely RESTful API can be assessed through Richardsons maturity levels.
🙏Thanks for taking the time to read the article. If you found it helpful and would like to show support, please consider:
- 👏👏👏👏👏👏Clap for the story and bookmark for future reference
- Follow me on Chaitanya (Chey) Penmetsa for more content
- Stay connected on LinkedIn.
Wishing you a happy learning journey 📈, and I look forward to sharing new articles with you soon.
