The Semantic Design RESTful Architecture
What is Representational State Transfer?
“Representational State Transfer (REST) is an architectural style consisting of a coordinated set of constraints applied to components, connectors, and data elements within a distributed Hypermedia system.
REST ignores the details of component implementation and protocol syntax in order to focus on the roles of components, the constraints upon their interaction with other components, and their interpretation of significant data elements.
The term REpresentational State Transfer was introduced and defined in 2000 by Roy Fielding in his doctoral dissertation at UC Irvine.”
– Wikipedia
Let us take at the classic definition above and decompose it into understandable sections.
The concepts below deals with the “Coordinated Set of Constraints“.
This awesome content and cool format
is courtesy of “WhatIsRest.com”
I found no reason to “Reinvent the Wheel” as my research into validating my beliefs found a site that represented them perfectly.
Please visit WhatIsRest.com for more details on the concepts presented in this post.
The formal REST constraints are listed below.
Each constraint is followed by an excerpt
from Roy Fielding’s Doctorate Dissertation
1 – Client-Server
Solution logic is separated into consumer and service logic that share a technical contract.
The Client-Server constraint requires that a service offer one or more capabilities and listen for requests on these capabilities.
A consumer invokes a capability by sending the corresponding request message, and the service either rejects the request or performs the requested task before sending a response message back to the consumer.
Exceptions that prevent the task from proceeding are raised back to the consumer, and the consumer is responsible for taking corrective action.
Roy Fielding:
“A client is a triggering process, a server is a reactive process.”
“Clients make requests that trigger reactions from servers.”
“Thus, a client initiates activity at times of its choosing; it often then delays until its request has been serviced.”
“On the other hand, a server waits for requests to be made and then reacts to them.”
“A server is usually a non-terminating process and often provides service to more than one client.”
“Separation of concerns is the principle behind the client-server constraints.”
“A proper separation of functionality should simplify the server component in order to improve scalability.”
“The separation also allows the two types of components to evolve independently, provided that the interface doesn’t change.”
2 – Stateless
The communication between service consumer (client) and service (server) must be stateless between requests.
This means that each request from a service consumer should contain all the necessary information for the service to understand the meaning of the request, and all session state data should then be returned to the service consumer at the end of each request.
Statelessness is one of the primary influences over service contract design in REST-style architecture.
It imposes significant restrictions on the kinds of communication allowed between services and their consumers in order to achieve its design goals.
Roy Fielding:
“The client-stateless-server style derives from client-server with the additional constraint that no session state is allowed on the server component.”
“Each request from client to server must contain all of the information necessary to understand the request, and cannot take advantage of any stored context on the server.”
“Session state is kept entirely on the client.”
“These constraints [Client-Server, Stateless] improve the properties of visibility, reliability, and scalability.”
“Visibility is improved because a monitoring system does not have to look beyond a single request datum in order to determine the full nature of the request.”
“Reliability is improved because it eases the task of recovering from partial failures.”
“Scalability is improved because not having to store state between requests allows the server component to quickly free resources and further simplifies implementation.”
“The disadvantage of client-stateless-server is that it may decrease network performance by increasing the repetitive data (per-interaction overhead) sent in a series of requests, since that data cannot be left on the server in a shared context.”
3 – Cache
Response messages from the service to its consumers are explicitly labeled as cacheable or non-cacheable.
This way, the service, the consumer, or one of the intermediary middleware components can cache the response for reuse in later requests.
The Cache constraint builds upon Client-Server and Stateless with a requirement that responses are implicitly or explicitly labeled as cacheable or non-cacheable.
Requests are passed through a cache component, which may reuse previous responses to partially or completely eliminate some interactions over the network.
This form of elimination can improve efficiency and scalability, and can further improve user-perceived performance by reducing the average latency during a series of interactions.
A common reason for incorporating caching as a native part of a REST architecture is as a counterbalance to some of the negative impacts of applying the Stateless constraint.
Roy Fielding:
“The client-cache-stateless-server style derives from the client-stateless-server and cache styles via the addition of cache components. A cache acts as a mediator between client and server in which the responses to prior requests can, if they are considered cacheable, be reused in response to later requests that are equivalent and likely to result in a response identical to that in the cache if the request were to be forwarded to the server.”
“Caching provides slightly less improvement than the replicated repository style in terms of user-perceived performance, since more requests will miss the cache and only recently accessed data will be available for disconnected operation. On the other hand, caching is much easier to implement, doesn’t require as much processing and storage, and is more efficient because data is transmitted only when it is requested. The cache style becomes network-based when it is combined with a client-stateless-server style.”
“The advantage of adding cache components is that they have the potential to partially or completely eliminate some interactions, improving efficiency and user-perceived performance.”
4 – Uniform Interface
The Interface constraint states that all services and service consumers within a REST-compliant architecture must share a single, overarching technical interface.
The technical contract established by Interface is typically free of business context because, in order to be reusable by a wide range of services and service consumers, it needs to provide generic, high-level capabilities that are abstract enough to accommodate a broad range of service interaction requirements.
Business-specific or service-specific data and meaning are isolated to the messages that are exchanged via the uniform technical contract.
Roy Fielding:
“REST provides a hybrid of the traditional client-server style sending a fixed format image to the recipient, mobile object style encapsulating the data with a rendering engine and sending both to the client, and sending the raw data to the recipient along with metadata that describes the type so the recipient can choose its own rendering engine options by focusing on a shared understanding of data types with metadata, but limiting the scope of what is revealed to a standardized interface.”
“REST components communicate by transferring a representation of a resource in a format matching one of an evolving set of standard data types, selected dynamically based on the capabilities or desires of the recipient and the nature of the resource.”
“Whether the representation is in the same format as the raw source, or is derived from the source, remains hidden behind the interface.”
“The key abstraction of information in REST is a resource.”
“Any information that can be named can be a resource: a document or image, a temporal service (e.g. “today’s weather in Los Angeles”), a collection of other resources, a non-virtual object (e.g. a person), and so on.”
“In other words, any concept that might be the target of an author’s hypertext reference must fit within the definition of a resource.”
“A resource is a conceptual mapping to a set of entities, not the entity that corresponds to the mapping at any particular point in time.”
“REST components perform actions on a resource by using a representation to capture the current or intended state of that resource and transferring that representation between components.”
“A representation is a sequence of bytes, plus representation metadata to describe those bytes.”
“Other commonly used but less precise names for a representation include: document, file, and HTTP message entity, instance, or variant.”
“A given representation may indicate the current state of the requested resource, the desired state for the requested resource, or the value of some other resource, such as a representation of the input data within a client’s query form, or a representation of some error condition for a response.”
“For example, remote authoring of a resource requires that the author send a representation to the server, thus establishing a value for that resource that can be retrieved by later requests.”
“If the value set of a resource at a given time consists of multiple representations, content negotiation may be used to select the best representation for inclusion in a given message.”
“REST enables intermediate processing by constraining messages to be self-descriptive: interaction is stateless between requests, standard methods and media types are used to indicate semantics and exchange information, and responses explicitly indicate cacheability.”
“Restricting the interface allows independently developed, services and consumers, to be arranged at will to form new applications.”
“It also simplifies the task of understanding how a given service or consumer works.”
“A disadvantage of the uniform interface is that it may reduce network performance if the data needs to be converted to or from its natural format.”
“By applying the software engineering principle of generality to the component interface, the overall system architecture is simplified and the visibility of interactions is improved.”
Implementations are decoupled from the services they provide, which encourages independent evolvability.”
The trade-off, though, is that a uniform interface degrades efficiency, since information is transferred in a standardized form rather than one which is specific to an application’s needs.”
“The REST interface is designed to be efficient for large-grain hypermedia data transfer, optimizing for the common case of the Web, but resulting in an interface that is not optimal for other forms of architectural interaction.”
5 – Layered System
A REST-based solution can be composed of multiple architectural layers, and no one layer can “see past” the next.
Layers can be added, removed, modified, or reordered in response to how the solution needs to evolve.
The Layered System constraint builds on Client-Server to add middleware components, which can exist as services or service agents, to an architecture.
Specifically, Layered System requires that this middleware be inserted transparently so that interaction between a given service and consumer is consistent, regardless of whether the consumer is communicating with a service residing in a middleware layer or a service that represents the ultimate receiver of a message.
Similarly, a service does not need to be aware of whether its consumer is further communicating with other services, or whether the consumer itself is also acting as a service for other consumer programs.
This form of information hiding simplifies distributed architecture and allows individual architectural layers to be deployed and evolved independently of specific services and consumers.
Roy Fielding:
“A layered system is organized hierarchically, each layer providing services to the layer above it and using services of the layer below it.”
“Although layered system is considered a “pure” style, its use within network-based systems is limited to its combination with the client-server style to provide layered-client-server.”
“The Layered-client-server adds proxy and gateway components to the client-server style.”
“A proxy acts as a shared server for one or more client components, taking requests and forwarding them, with possible translation, to server components.”
“A gateway component appears to be a normal server to clients or proxies that request its services, but is in fact forwarding those requests, with possible translation, to its “inner-layer” servers.”
“These additional mediator components can be added in multiple layers to add features like load balancing and security checking to the system.”
“The layered system style allows an architecture to be composed of hierarchical layers by constraining component behavior such that each component cannot “see” beyond the immediate layer with which they are interacting.”
“By restricting knowledge of the system to a single layer, we place a bound on the overall system complexity and promote substrate independence.”
“Layered systems reduce coupling across multiple layers by hiding the inner layers from all except the adjacent outer layer, thus improving evolvability and reusability.”
“Examples include the processing of layered communication protocols, such as the TCP/IP and OSI protocol stacks, and hardware interface libraries.”
“The primary disadvantage of layered systems is that they add overhead and latency to the processing of data, reducing user-perceived performance.”
“LCS is also a solution to managing identity in a large-scale distributed system, where complete knowledge of all servers would be prohibitively expensive.”
“Instead, servers are organized in layers such that rarely used services are handled by intermediaries rather than directly by each client.”
“Layers can be used to encapsulate legacy services and to protect new services from legacy clients, simplifying components by moving infrequently used functionality to a shared intermediary.”
“Intermediaries can also be used to improve system scalability by enabling load balancing of services across multiple networks and processors.”
6 – Code On Demand (Optional)
This “Optional Constraint” is primarily intended to allow logic within clients, such as Web browsers, to be updated independently from server-side logic.
Code-On-Demand typically relies on the use of Web-based technologies, such as Web browser plug-ins, applets, or client-side scripting languages (i.e. JavaScript).
Code-On-Demand can further be applied to services and service consumers.
For example, a service can be designed to dynamically defer portions of logic to service consumer programs.
For example, this type of functionality can be used in support of Stateless, which dictates whether a session state should be deferred back to the service consumer.
Code-On-Demand can also build upon this by further deferring the processing effort.
This approach may be justifiable when service logic can be executed by the consumer more efficiently or effectively.
Roy Fielding:
“In the code-on-demand style, a client component has access to a set of resources, but not the know-how on how to process them.”
“It sends a request to a remote server for the code representing that know-how, receives that code, and executes it locally.”
“REST allows client functionality to be extended by downloading and executing code in the form of applets or scripts.”
“This simplifies clients by reducing the number of features required to be pre-implemented.”
“Allowing features to be downloaded after deployment improves system extensibility.”
“However, it also reduces visibility, and thus is only an optional constraint within REST.”
“The advantages of code-on-demand include the ability to add features to a deployed client, which provides for improved extensibility and configurability, and better user-perceived performance and efficiency when the code can adapt its actions to the client’s environment and interact with the user locally rather than through remote interactions.”
“Simplicity is reduced due to the need to manage the evaluation environment, but that may be compensated in some cases as a result of simplifying the client’s static functionality.”
“Scalability of the server is improved, since it can off-load work to the client that would otherwise have consumed its resources.”
“Like remote evaluation, the most significant limitation is the lack of visibility due to the server sending code instead of simple data.”
“Lack of visibility leads to obvious deployment problems if the client cannot trust the servers.”
What is a “Representation”?
In the second part of the definition it states;
“REST ignores the details of component implementation and protocol syntax in order to focus on the roles of components, the constraints upon their interaction with other components, and their interpretation of significant data elements”
A “Representation” is the abstraction of a concrete “Resource“. A “Resource Representation” is generally a pluralized noun: Customers.
A Resource conveys a visual image of a thing, it is not an “Action Verb” like calls made with a traditional Remote Procedural Call (RPC) SOAP Protocol: getCustomers.
As Roy Fielding states:
“REST components communicate by transferring a representation of a resource in a format matching one of an evolving set of standard data types, selected dynamically based on the capabilities or desires of the recipient and the nature of the resource.”
Let’s take a real world example: People:
People can be a Representation of a number of different types of Resources:
Customers |
Vendors |
Employees |
Dependents |
Contractors |
Clients |
Colleagues |
Constituents |
Lobbyists |
Politicians |
Now let’s imagine we can dynamically decide from the “People” representation the “Resources” one of the types listed above in the nanosecond that the request is made to the Uniform Interface: HTTP.
The “Client-Server Constraint” has One Preeminent Principle:
The Client Requires No Knowledge of the Server
… The Server has No Knowledge of the Expectations of the Client
The “Stateless Constraint” has One Preeminent Principle:
The Client Requires No State Information
… It Holds the Most Current Application State
The Server Hold the “Last Known State”
… As the “Recovery State” in Case of Intermittent Failure
The “Uniform Interface Constraint” has One Preeminent Principle:
The Ability for the Resource Representation
… To Be Dynamically “Self Describing”
The “Cache Constraint” has One Preeminent Principle:
Create the Ability through the Uniform Interface
… To Define Application State Caching
As you can see from the implementations of the key constraints above, using a RESTful Architecture we can deliver ten different concrete payloads to a Client’s Webpage that only understands the “People Representation“.
By implementing “Semantic Modeling“, ten different kinds of “People Resources” are available by a Self-describing, dynamically generated, “Semantic Definition Hyperlink” that defines one type of “People” to be delivered to the Client using the Uniform Interface: HTTP.
… In Conclusion
It is my goal in this post to introduce you to the basics of the REST Architecture originally described by Roy Fielding.
He created the HTTP Protocol to act as his Uniform Interface after working on the early World Wide Web specifications with the W3C Web community.
In another post we will discuss Hypermedia and the worst acronym ever: HATEOAS
The RESTful Architecture Create the Framework
for Semantic Modeling in the Semantic Design Series
Wisdom Pearl # 128 – How Do You Deal With Fear of Failure
People Either Run Towards Pleasure
… Or Away from Pain
Be Willing to Risk the Pain of Failure
… For the Pleasure of Success
Latest posts by Brad Huett (see all)
- DevOps: A Bridge to Your DevOps Culture - March 25, 2016
- Embracing Test Driven Development (TDD) - March 25, 2016
- DevOps: Delivering Agile Projects - March 25, 2016