RESTful Web Services

Background

Welcome to this blog post where I will be sharing a paper I wrote on RESTful web services implementation around April 2010. The original purpose of this paper was to provide guidance for developers implementing RESTful web services within the Global Command and Control - Integrated Imagery & Intelligence (GCCS-I³) architecture team and the Joint Command & Control (Joint C2) architecture group. The aim was to review the current Joint C2 architecture documents, provide implementation guidance and industry practices, and demonstrate how current DoD standards and mandates could fit in. The paper was received well by various organizations, including MITRE, DISA, ONI, and Northrop Grumman. It was also used as research for a book on REST, reviewed by folks attending the WWW 2010 conference, and was even utilized by various groups at Microsoft as an introduction to the REST architectural style.

Although this paper was written a while ago, I believe that it still holds relevance today. With software cycles and history repeating itself, the ideas presented in this paper are still applicable to today's software development landscape. As the web becomes more important than ever, it is essential to have an understanding of RESTful web services implementation and the benefits it offers. Therefore, I have decided to turn this paper into a blog post to make it more accessible to a wider audience and to allow for easier sharing and engagement. I've only modified a few minor details to better fit the blog post style vice a formal paper. Additionally, I believe that keeping this paper as a historical record of my research and thinking at the time is essential. So, without further ado, let's dive into the world of RESTful web services!

Origins

To understand REST, one needs to first take a look back at history and understand the evolution of distributed applications and the World Wide Web.

What many people don't realize is that drawing pictures, writing documents no-one reads, meta-modeling, and pontificating on 'concerns' are not software architecture. Software architecture is about introducing constraints via principled, objective design to achieve particular system properties.

Bill de Hora

Distributed and Network-Based Systems

The term "distributed application]" is typically used to describe anything from a multi-threaded application running across many operating system processes on one CPU to integrated applications spanning multiple computers over a network like the Internet. These applications have been around since the early days of computing and have manifested in methods of hiding network operations behind the abstraction of the hosts programming language procedure calls. This illusion of "location transparency" is known as a Remote Procedure Call (RPC), which is exemplified in distributed technologies like CORBA, EJB, and SOAP-based Web Services. One key motivation behind the design of RPC is to mimic the object-oriented development style for distributed computing attempting to shield the developer from issues and concerns associated with the network. However, this kind of transparency can never fully shield the developer from the network.

Tanenbaum and van Renesse ... make a distinction between distributed systems and network-based systems: a distributed system is one that looks to its users like an ordinary centralized system, but runs on multiple, independent CPUs. In contrast, network-based systems are those capable of operating across a network, but not necessarily in a fashion that is transparent to the user. In some cases it is desirable for the user to be aware of the difference between an action that requires a network request and one that is satisfiable on their local system, particularly when network usage implies an extra transaction cost ...

Roy T. Fielding

Masking the network and its properties from the developer brings multiple problems which have been recognized by industry and canonized by Peter Deutsch and James Gosling in a short list known as the "Fallacies of Distributed Computing" and a paper by Waldo et al titled A Note on Distributed Computing.

Essentially everyone, when they first build a distributed application, makes the following eight assumptions. All prove to be false in the long run and all cause big trouble and painful learning experiences.

1. The network is reliable.
2. Latency is zero.
3. Bandwidth is infinite.
4. The network is secure.
5. Topology doesn't change.
6. There is one administrator.
7. Transport cost is zero.
8. The network is homogenous.

Peter Deutsch

The World Wide Web

The Web was designed by Tim Berners-Lee in the early 1990's as a distributed hypermedia application to allow sharing of information. Since all of the information being shared on the Web has to flow over a network, all of the issues described in the Fallacies of Distributed Computing apply to the Web. Tim Berners-Lee and others involved in the design and implementation of web protocols and standards, such as HTTP and URI, understood that the Web would need to address issues around latency, scale, contention of resources (multi-user/ multi-owner environment), lack of a centralized authority (within a heterogenous environment that crossed organizational boundaries), etc. From the very beginning, Web technologies and protocols were constrained to exhibit properties like high performance (including network performance, user-perceived performance, and network efficiency), anarchic scalability, simplicity, modifiability (including evolvability, extensibility, customizability, configurability, and reusability), visibility, portability, and reliability. The Web provides a uniform application protocol for coordination between resources.

To understand the context for the creation of REpresentational State Transfer (REST), one needs to understand the properties and characteristics of the Web first. The web was formed on solid engineering principles such as separation of concerns and simplicity, but lacked a clear definition of the constraints used to induce the exhibited properties. Roy T. Fielding created the REST architectural style at a time when the Web was just starting off experiencing extreme rapid growth. There was a need to identify the key constraints of the Web that made it so successful and extend those constraints to induce desirable properties for an Internet-scale distributed hypermedia system that would define a style for modern Web architecture. Architects could then communicate and compare proposals that would modify and extend the Web to the constraints in the new hybrid style.

Architecture Primer

When discussing REST, the many terms related to the practice of software architecture that arise can be confusing. Particularly when stating that REST is an architectural style and not an architecture or specific implementation. To improve communication, a definition of terms and an example using a well known system is helpful. Fielding used the Web to help clarify the differences between implementation, architecture, and architectural styles.

Implementation of the Web

Implementation is the specific information, software, and tools that define a concrete form of a given architecture. For instance, the implementation of the Web consists of all Web pages and associated addressable information along with the software hosting or utilizing those resources like the WebLogic application server, Apache Web server, Internet Explorer, Firefox, Squid Proxy, etc.

Architecture of the Web

Architecture is an abstraction of an implementation. The key design decisions related to system structure, functional behavior, interaction, nonfunctional properties, and system implementation comprise a software architecture. For instance, a Web architecture consists of various protocols and formats that define the form and meaning behind the interaction of components like URI, HTTP, and HTML.

A software architecture is an abstraction of the run-time elements of a software system during some phase of its operation. A system may be composed of many levels of abstraction and many phases of operation, each with its own software architecture.

Roy T. Fielding

Architectural Style

Architectural styles are used for categorizing and defining common characteristics of a system. Styles are used for communication rather than the system architecture, since the software architecture of a system comprises both functional and non-functional properties which are difficult to directly compare. Similar to how building architects describe Gothic, Baroque, Neoclassical, Doric, or any number of architectural styles, software architects use architectural styles as a way to name patterns. This vocabulary helps architects communicate better for comparing, contrasting, and designing systems. The easier it is to communicate, the faster innovation and change can happen.

An architectural style is a named collection of architectural design decisions that (1) are applicable in a given context, (2) constrain architectural design decisions that are specific to a particular system within that context, and (3) elicit beneficial qualities in each resulting system.

Software Architecture: Foundations, Theory, and Practice (Taylor et al. 2010)

Architecture Summary

To summarize, an architecture usually consists of multiple architectural styles and a comparison of those styles is based on the properties the style exhibits. Architects can discuss how a given implementation compares to an intended architecture that is an example of a given architectural style. For instance, REST is an architectural style; a RESTful web services architecture typically will consist of protocols and standards like HTTP, URI, MIME, etc.; an implementation of that architecture could be through using the Jersey framework, JBoss application server, all exposed resources, etc.

REpresentational State Transfer (REST)

REpresentational State Transfer, or more commonly REST, is an architectural style defined by Roy T. Fielding in his doctoral dissertation, Architectural Styles and the Design of Network-based Software Architectures. REST declares a set of constraints that when used properly results in benefits and characteristics including higher scalability, fault-tolerance, increased security and visibility, amongst others. This brings out everything the Web is capable of for free without the need to buy or adopt an entire new software stack.

REST is an architectural style that, when followed, allows components to carry out their functions in a way that maximizes the most important architectural properties of a multi‐organizational, network‐based information system. In particular, it maximizes the growth of identified information within that system, which increases the utility of the system as a whole.

Roy T. Fielding

The Benefits of REST

The communication between systems today usually comes at the price of tight coupling, even though some technologies have claimed to be loosely-coupled. In the early days of SOAP-based Web Services, if a service provider modified their interface to use a different method, format, or location, a consumer who was previously using that service would more often than not be broken. Versioning can sometimes help but in reality tends to act as a band-aid that still couples the client to the service endpoint requiring the client and server to move in lock-step. Interoperability problems related to modified data formats, interfaces, and complex technologies have plagued SOAP-based Web Service providers and consumers in industry, the Department of Defense (DoD), and more specifically the Intelligence Community (IC). To get the most out of net-centric systems technologies relies on reduced coupling between components and the systems using them.

Heterogeneous environments like the Web or enterprise systems based on Service Oriented Architecture (SOA) like I³ and Joint C2 will need to support unanticipated ways that the client will interact with a service. Services will need to be adaptable, scalable, visible, maintainable, efficient, reliable, and reusable. REST deliberately designed all of these properties (and others) into an architectural style from the beginning rather than as an afterthought. REST is not a silver bullet or the only solution to a problem, but it tends to be the more straightforward, simpler, and proven approach for distributed systems design.

All of the constraints of REST were designed to keep systems living longer than we are willing or able to anticipate. Other things that might be worth keeping in mind is that REST is designed for reuse, not just use. The notion that anyone has control over a successful application's reuse is pure fantasy.

Roy T. Fielding

Business Case

Not everyone is technical or needs to understand the computer science aspects of a given approach. For them, the business case that revolves around cost and risk is the most important piece to understand. RESTful systems excel in both.

REST does not require costly vendor specific middleware and large software stacks. The typical middleware, frameworks/libraries, and tools that are used to implement REST like the Apache Web Server, Squid Proxy/Cache, and J2EE servlet implementations are usually free, widely supported, proven from years of use, and are based on very common industry standards like HTTP, URI, MIME, and XML. Typical complex, expensive, and proprietary products like an Enterprise Service Bus (ESB), UDDI registries, and orchestration engines are not needed since the relevant concepts and capabilities those and similar products provide were baked in to the REST architectural style.

Since REST relies on common industry standards, tools, and frameworks, there is a low barrier to entry for developers, meaning less time wasted learning new technologies and less money spent hiring specialists. The common and commoditized technologies also extend past development into production and maintenance due to the ability to take advantage of current people and tools that already host, monitor, and test Web applications. This translates into not only short-term benefits but a long-term lower cost of ownership.

REST implementations typically do not have the traditional road blocks related to licenses, costly middleware, and complex technologies. They have the benefits of using common platforms and technologies. This means that RESTful systems following agile practices could deploy more often and get incremental feedback from various stakeholders lowering project risk. Along the same lines of risk reduction, REST aligns nicely with the DoD's Net-Centric Data and Services Strategy positioning a project for immediate work and future growth.

Show Me

Despite all of the convincing arguments for REST, it can still be quite difficult to convince or persuade someone to go down this path. Some reasons for this are the following:

1. REST's simplicity can act as a double-edged sword. Some believe complex solutions are the only answer and do not invest the time to understand the details.
2. Large software vendors have not yet figured out how to sell REST as a product and have already sold costly middleware to the enterprise.
3. Decision makers can sometimes entrench themselves in approaches that are difficult to go back on without damaging their reputations.

In these cases, the best selling point is to actually implement a RESTful web service and show that it can be done in a short amount of time with less overhead. This document will help to demonstrate this through examples and practical guidance.

Derivation of REST

REST is an architectural style derived from a number of other architectural styles. More formally, REST is a named set of constraints on component interaction that, when obeyed, cause resulting architectures to have certain properties.

The architectural styles (listed as Style Constraint) and related properties and trade-offs mentioned in table above result when the given style is considered in isolation. When architectural styles are mixed, the combinations can induce different properties and trade-offs. These combinations may offset the trade-offs of a particular style as well. For instance, Fielding describes in his dissertation how the primary disadvantage of a Layered System style is reduced user-perceived performance due to the overhead and amount of time required to process data. This can be offset by combining the Layered System style with the Cache style in order to gain performance improvements.

The REST architectural style is derived from various architectural styles, namely the styles listed in the table below. The REST hybrid style can therefore be described as a Uniform-Layered-Client-Cache-Stateless-Server (ULC$SS) or with the optional Code on Demand constraint as a Uniform-Layered-Code-on-Demand-Client-Cache-Stateless-Server (ULCODC$SS).

The Uniform Interface Explained

The central feature that distinguishes REST from other network-based architectural styles is the uniform interface that defines four interface constraints. One key motivation behind the uniform interface is to enable generic interactions thereby loosely-coupling the client (agent) from the server. Another goal is the discovery of capability and transitions through media types that describe processing and meaning of representations.

The table below describes each one of the interface constraints while subsequent sections go into more detail.

Uniformity in Implementation

A common misconception in applying the REST architectural style to implementation, as in RESTful web services, is to think that the uniform interface is only about the HTTP methods (e.g. GET, PUT, POST, DELETE, OPTIONS, and HEAD). REST is not file storage.

The HTTP methods only fulfill one part of the uniform interface constraint related to resource generic interaction semantics. To understand uniformity in implementation, as in RESTful web services, one would have to look beyond HTTP to analyze REST. For instance, one would look at MIME, URI, media-types like Atom or RDF. However, this is not to say that these technologies are the only way to implement a RESTful system. Fielding states that "REST does not restrict communication to a particular protocol" like HTTP. A system like <1060>'s NetKernel is a prime example of this. Fielding is also using REST to guide the creation of an HTTP replacement he calls Waka.

Resources

Resources are conceptual abstractions for any significant and interesting piece of an application that is made addressable and could be useful to others. They are the key abstraction of information that can be anything ranging from the latest version of this document, a business process, the number of insurgent attacks in a specific Area of Interest (AOI) in Afghanistan for February 2010, to a collection of search results referencing related resources. The resource is mapped to a set of entities or values that contain resource representations and resource identifiers. Resources can also be mapped to nothing in order to allow for the realization of future resources. The semantics, or meaning, of the resource does not change but the values often do.

This abstract definition of a resource enables key features of the Web architecture. First, it provides generality by encompassing many sources of information without artificially distinguishing them by type or implementation. Second, it allows late binding of the reference to a representation, enabling content negotiation to take place based on characteristics of the request. Finally, it allows an author to reference the concept rather than some singular representation of that concept, thus removing the need to change all existing links whenever the representation changes (assuming the author used the right identifier).

Roy T. Fielding

Addressability

Resources are typically broken down into their smallest granularity to avoid complexity, enable referencing, and promote reusability. They are the fundamental pieces that clients interact with to progress towards a desired goal (possibly in ways the resource implementor never imagined). In order to enable these goals, the interesting things need to be identifiable or addressable making a system "resource-oriented". Typically, RESTful web services and other RESTful implementations will use a Uniform Resource Identifier (URI) to uniquely identify resources. A URI may reference only one resource, but a resource may have multiple URI's.

In the past, there has been some heated debates in the REST community around transparent vs. opaque identifiers for URI design. Today, most agree that there should be a balance between the two depending on the viewpoint. For instance, from a server perspective, the identifier should be transparent and informative to help organize and document design time resources and hierarchies. URI templates are put to use in order to account for dynamic resources that the server can mint at run time. From an agent or consumer perspective, URI's should generally remain stable (or cool) but somewhat opaque to allow for bookmarking of an entry point into the RESTful application workflow where URI's and their meaning are discovered through hypermedia. One advantage of hypermedia is that new features can be introduced without breaking existing consumers. Any knowledge of the URI template (not detailed in a given media type) that the consumer contains suggest a priori knowledge leading to a more tightly coupled system. This has implications for versioning as well.

Statelessness

The interaction with resources are context-free, meaning that each request must contain all the necessary information needed to understand and process the message without any stored information on the server (e.g. sessions). Since the client holds the context, the server can scale easier through clustering and/or cloud environments, enforce visibility and service level agreements through improved monitoring capabilities, and aid in service reliability due to mainly idempotent interactions that can enable partial recovery in Disconnected, Intermittent, and/or Limited (DIL) network communication conditions.

Representations

An important concept is the difference between resource state and application state. A resource representation contains resource state and representation metadata. The server guides the consumer in-band by offering transition links, related resource links, various metadata and control data, and typed relations (e.g. microformats, RDF in N3 or XML, SVG) in the representations. Application state is maintained and inferred by the consumer accessing the various resources. Consumers interact with and change resource state by manipulation of the representations exposed by the resources.

Each resource has one or more representations that are views into the resource state at any given time. A RESTful resource may expose Atom, JSONC, UCore, or any other representation media type. REST does not require that any specific format should be used, but it does require the formats to be hypermedia aware. Media types that are hypermedia aware describe links, link relations (what the link means), parsing instructions and more importantly processing rules. Content negotiation (conneg) is used to mediate suggested and requested representation formats in order to support a wide variety of consumers and needs.

Self-Descriptive Messages

Along with the hypermedia constraint, self-descriptive messages are extremely important to the REST architectural style because it implies many of the other constraints. This constraint means that every message must contain all the necessary bits of information in order to process and understand the message. This is accomplished through the use of representation metadata (like media types), resource metadata (like source links), control data (like the if-modified-since HTTP header), and the other uniform interface constraints.

In short, if you can draw a state machine in which each state is self-described (resident on the client), the transitions from that state are also self-described (instructions for the client to initiate), and each transition is invoked using a self-descriptive message, then you have a RESTful application. All of the rest of the constraints fall out from the need to be self-descriptive (i.e., generic methods are necessary because resource-specific behavior is too complex to be self-descriptive).

Roy T. Fielding

The Hypermedia Constraint

The hypermedia constraint is what gives REST most of its interesting architectural characteristics. For the most part, the Web has been described in various IETF RFC's and the W3C's Web architecture. However, the difference that REST presents is a fresh perspective on how the Web could be used. Before REST, the Web was viewed as a way to share, view, and manipulate information. REST shined a light on how the Web could be used as a platform for hosting distributed applications without the need for expensive and complex middleware through the use of hypermedia.

The next control state of an application resides in the representation of the first requested resource, ... The application state is controlled and stored by the user agent ... anticipate changes to that state (e.g., link maps and prefetching of representations) ... The model application is therefore an engine that moves from one state to the next by examining and choosing from among the alternative state transitions in the current set of representations.

Roy T. Fielding

To Be Great is to Be Misunderstood

Hypermedia as the engine of application state (HATEOAS), more commonly referred to as the hypermedia constraint, is arguably the most important constraint in the uniform interface. The concept of the hypermedia constraint is very powerful, but it can be a difficult idea to grasp. Fielding has outlined a few reasons why he thinks the confusion exists:

1. Fielding takes some of the heat by explaining that he ran out of time before he was able to add a section on media-type design to his dissertation.
2. Lots of misinformation on the internet with no referenced authoritative sources.
3. REST was designed for longevity, but most people are good at designing for the now or immediate future.
4. Fielding also discusses how his paper was written for experts in the field of software engineering and network protocol design where many readers and interpreters today are not a part of that specialized audience.
5. Fielding believes that just because something is simple, doesn't mean that it is easy to design. In fact, he suggests that the "effort required to design something is inversely proportional to the simplicity of the result." One of REST's goals as an end result is extreme simplicity.
6. The first book on the subject, RESTful Web Services, did not do a good job describing hypermedia by referring to it as "connectedness."

Hypermedia Simplified

Architects sometimes have a way of making concepts more difficult than they actually are. Despite all of the confusion, hypermedia is actually a simple concept that has been described as one level of abstraction above a traditional message passing architecture. The concept of starting at a web page, reading the page, finding links, clicking on the links, and receiving a new page is very easy to understand for just about anyone who has ever used the Web. The hypermedia constraint defined in the REST architectural style simply states that what works for humans should also work for machines.

When I say hypertext, I mean the simultaneous presentation of information and controls such that the information becomes the affordance through which the user (or automaton) obtains choices and selects actions. Hypermedia is just an expansion on what text means to include temporal anchors within a media stream; most researchers have dropped the distinction. Hypertext does not need to be HTML on a browser. Machines can follow links when they understand the data format and relationship types.

Roy T. Fielding

Resources are modeled as states. Representations describe the current state of a given resource and provide links that the client could potentially transition towards. The client controls the application state machine freeing the server of storing state and having scalability issues. Hypermedia enables dynamic protocol description and discovery thereby loosely coupling the client and server to a given media type.

The idea is really simple and, yet, very powerful. A distributed application makes forward progress by transitioning from one state to another, as in a state machine. The difference from traditional state machines, however, is that the possible states and the transitions between them are not known in advance. Instead, as the application reaches a new state, the next possible transitions are discovered. It's like a treasure hunt.

REST In Practice

Media Types

In order for an agent to understand how to transition to a next state, the agent needs to be able to process links and understand the semantics of that link. More simply put, media types communicate what the current representation means and what is on the other side of the link. Generic media types like application/xml are not acceptable in a RESTful sense since they don't have well-defined meaning around the links and link relations. However, that's not to say that media types can't be built from general purpose formats. Typical RESTful representations will use hypermedia aware media types like Atom, APP, JSONC, and RDF that explicitly define links and processing rules and are built off of general purpose formats like XML and JSON. Almost all of the design around a RESTful system should be related to the media type. All communication is dependent on some form of prior knowledge and in REST's case it is the media type.

In a truly RESTful system, almost all coupling between client and server is reduced to the media types they exchange.

Richard L. Apodaca

Sometimes the industry standard media types like Atom or RDF will not suffice for a given domain. Fortunately, REST does not prescribe any one representation format and media type, but it does require the format to be hypermedia aware (defining links and related link relations). Some options to consider are a Domain Application Protocol (DAP) and extensions of standard media types. However, as the book REST in Practice describes, there is a tradeoff between reach and utility when defining your own DAP rather than using a general purpose media type. Understanding the proper balance between the tradeoffs and the domain specific needs while extending or taking advantage of general purpose protocols will help to avoid a Tower of Babel and a tightly-coupled system.

The choice depends on a tradeoff between reach and utility—between the ability to leverage existing widely deployed software agents and the degree to which a format matches our domain's needs ... Underlying the Web is a principle of generality, which prefers a few commonly agreed, general-purpose formats to many specialized formats. The principle of generality allows huge numbers of different programs and systems to interoperate using a few core technologies.

REST In Practice

REST API's Must Be Hypertext-Driven

When attempting to implement RESTful web services, many designers, developers, and architects forget that hypermedia must be transitioning the client through various states. The most often violated rules related to the hypertext constraint and their implications are detailed below according to Roy Fielding in his blog post titled REST API's Must Be Hypertext Driven:

Richardson Maturity Model

The idea behind REST was to extract the principles that made the current Web successful and identify a roadmap for the next-generation of the Web. The constraints enforced by REST and the properties they enable are sometimes misunderstood and disassociated from the hype and popularity the industry has created around the term. Instead of a way to communicate architectural properties and guidance, REST has become a buzzword associated solely with HTTP style web services. Therefore, many popular API's today claim to be RESTful when in fact they are not.

An expert on the REST architectural style can usually identify the violations of such API's, but stating that something is not RESTful without demonstrating why is a somewhat subjective way to communicate. In response to the industry confusion and as a means of communicating the differences in terms of implementation rather than theoretical concepts, Leonard Richardson defined a maturity heuristic for determining if a service is RESTful based on the Web's implementation technology stack.

The reason this model is useful is that these three technologies are the real-world implementation of the RESTful constraints. It's difficult to talk about hypermedia as the engine of application state but it's not difficult to talk about HTML and URIs, which embody that constraint on the World Wide Web.

Leonard Richardson

Level 0

Level zero services typically have only one URI and utilize only one of the HTTP methods. For instance, SOAP-based (WS-*) Web Services have multiple methods defined in a WSDL that are all called using HTTP's POST method using a single URI. Richardson likens this level of service to Flash-based Web applications since they are like a complicated black box atypical of open Web technologies. Lots of interesting things or resources may be living in this black box which are not individually addressable. Each one of these services usually requires the client to relearn the semantics and required interaction of the server's API, thereby tightly coupling the client and server. Another prime example that falls under this realm are the OGC-based services (WMS, WFS, WCS). These services attempt to duplicate the underlying HTTP protocol while tunneling over it and do not follow the uniform interface constraint. Other examples include XML-RPC and POX services which also employ the service endpoint anti-pattern. Besides "Web" being in the name of many of these service styles, they really don't share any of the properties or useful characteristics of the Web.

Level 1

Level one services typically have multiple URI's but still use only one HTTP method. These are what many of the industry web services (e.g. Flickr and some of Amazon's API's) are that claim to be RESTful. Many RESTafarians, or REST advocates, get frustrated with this service style because they are not RESTful but claim to be and they have serious architectural problems. Despite this, the level one service style is still being created and is very popular being used over and over again. Richardson believes this is due to the the complexity being broken out and each interesting thing or resource having its own URI. The resources are addressable which make it easy to reference, bookmark, and mash-up information.

Level 2

Level two services expose many URI's with each supporting multiple HTTP methods. A good example of this service style is Amazon's S3 API. Another commonly misunderstood approach is WS-Transfer, which is a level zero standard, but defines a CRUD-like interface that is similar to the HTTP methods. These services in level two are commonly known as CRUD (Create, Read, Update, Delete) services as they usually contain good intentions, but ignore the hypermedia constraint.

Most well thought out SOA approaches, or even 'naive' REST approaches, begin to use many of RESTs constraints: they adopt URIs for most interesting things in the system, and take advantage of a uniform transfer protocol to underlie the representations. But, they sometimes choose to ignore the hypermedia constraint. With this approach there is still big benefit in the separation between the semantics, representation, and location or authority of information that is made explicit. But there still is a somewhat tightly coupled end-result: the temporal assumptions are defined & controlled completely by the provider interfaces, and the consumer is subject to their whim.

Stu Charlton

Level 3

Level three services are truly RESTful as they have many URI's each using multiple HTTP methods and more importantly resources describe their own capabilities, transitions, and relations. Richardson compares these services to the Web, AtomPub (APP), and the Netflix API.

Relaxing Constraints

It's OK to not utilize all the constraints of REST, but their needs to be a shared understanding of what that means. For one, relaxing any of the defined constraints of REST makes the service or API not RESTful, so the design should not be called so. Also, some of the useful properties induced by the constraints are lost. An understanding of why the properties are needed or not should be evaluated. The reasons for introducing or removing constraints should be through principled objective design to achieve desired properties that are known as a result of experience in the application domain.

The evaluation of architectural properties within a tree of styles is specific to the needs of a particular application domain because the impact of a given constraint is often dependent on the application characteristics. For example, the pipe-and-filter style enables several positive architectural properties when used within a particular system that requires data transformations between components, whereas it would add nothing but overhead to a system that consists only of control messages.

Roy T. Fielding

Summary

This post served to demonstrate the reasons and motivation behind the REST architectural style, describe what REST is, and improve communication through architectural terms and guidance. It serves as the foundation for further exploration on RESTful web services and suggests ways of designing architectures through principled design. As Roy Fielding states, "the specific needs of an application [should] be matched against the properties of the design" or architectural style.

Hint: A RESTful system progresses from one steady-state to the next, and each such steady-state is both a potential start-state and a potential end-state. I.e., a RESTful system is an unknown number of components obeying a simple set of rules such that they are always either at REST or transitioning from one RESTful state to another RESTful state. Each state can be completely understood by the representation(s) it contains and the set of transitions that it provides, with the transitions limited to a uniform set of actions to be understandable. The system may be a complex state diagram, but each user agent is only able to see one state at a time (the current steady-state) and thus each state is simple and can be analyzed independently. A user, on the other hand, is able to create their own transitions at any time (e.g, enter a URL, select a bookmark, open an editor, etc.).

Roy T. Fielding

See the associated LinkedIn post.