Quotes have been taken from Roy Fielding's blog posts writings and own comments.
Article: REST APIs must be hypertext-driven.
A REST API should spend almost all of its descriptive effort in defining the media type(s) used for representing resources and driving application state, or in defining extended relation names and/or hypertext-enabled mark-up for existing standard media types. Any effort spent describing what methods to use on what URIs of interest should be entirely defined within the scope of the processing rules for a media type (and, in most cases, already defined by existing media types). [Failure here implies that out-of-band information is driving interaction instead of hypertext.]
[...] if the engine of application state (and hence the API) is not being driven by hypertext, then it cannot be RESTful.
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.
The following would aim at JSON or XML data as a response?
A truly RESTful API looks like hypertext. Every addressable unit of information carries an address, either explicitly (e.g., link and id attributes) or implicitly (e.g., derived from the media type definition and representation structure). Query results are represented by a list of links with summary information, not by arrays of object representations (query is not a substitute for identification of resources). Resource representations are self-descriptive: the client does not need to know if a resource is OpenSocialist because it is just acting on the representations received.
How many Web browsers are aware of the distinction between an online-banking resource and a Wiki resource? None of them. They don’t need to be aware of the resource types. What they need to be aware of is the potential state transitions — the links and forms — and what semantics/actions are implied by traversing those links. A browser represents them as distinct UI controls so that a user can see potential transitions and anticipate the effect of chosen actions. A spider can follow them to the extent that the relationships are known to be safe. Typed relations, specific media types, and action-specific elements provide the guidance needed for automated agents.
REST is software design on the scale of decades: every detail is intended to promote software longevity and independent evolution. Many of the constraints are directly opposed to short-term efficiency. Unfortunately, people are fairly good at short-term design, and usually awful at long-term design. Most don’t think they need to design past the current release. There are more than a few software methodologies that portray any long-term thinking as wrong-headed, ivory tower design (which it can be if it isn’t motivated by real requirements).
To some extent, people get REST wrong because I failed to include enough detail on media type design within my dissertation. That’s because I ran out of time, not because I thought it was any less important than the other aspects of REST.
The media type identifies a specification that defines how a representation is to be processed. That is out-of-band information (all communication is dependent on some prior knowledge).
Resources are not storage items (or, at least, they aren’t always equivalent to some storage item on the back-end). The same resource state can be overlayed by multiple resources, just as an XML document can be represented as a sequence of bytes or a tree of individually addressable nodes.
In terms of testing a specification, the hardest part is identifying when a RESTful protocol is actually dependent on out-of-band information or if the authors are just overspecifying things for the purpose of documentation. What I look for are requirements on processing behavior that are defined outside of the media type specification. One of the easiest ways to see that is when a protocol calls for the use of a generic media type (like application/xml or application/json) and then requires that it be processed in a way that is special to the protocol/API. If they are keying off of something unique within the content (like an XML namespace declaration that extends the semantics of a generic type), then it’s okay. Usually, however, what they do is assume that the response has a specific structure beyond that defined by the media type. When the structure changes, the client will break.
[...] if your client relies on the resource being a [a certain type], then it certainly isn’t a RESTful API. [...] If a client is receiving instructions on how to interact with a resource just before acting only on those instructions, then the client doesn’t care [...] to know how the resource is implemented.
Article: It is okay to use POST
The only thing REST requires of [HTTP] methods is that they be uniformly defined for all resources (i.e., so that intermediaries don’t have to know the resource type in order to understand the meaning of the request). As long as the method is being used according to its own definition, REST doesn’t have much to say about it.
POST serves many useful purposes in HTTP, including the general purpose of “this action isn’t worth standardizing.”
Ultimately, the methods should be chosen by the origin server and communicated somehow to the client via the media type or relationship processing rules.
[...] the design constraints of REST should be used when they are useful, not just because they are RESTful.
Nevertheless, there are plenty of information systems that can be designed using the REST architectural style and gain the associated benefits. Managing cloud instances is certainly one of those applications for which REST is a good fit.
Representational State Transfer (REST) is a software architectural style that describes how to construct network-based software applications such that they have the best characteristics of the Web. It acts as a guide for analysing and comparing software design choices, evaluating protocol decisions, and teaching the effect of design constraints on system properties such as simplicity, evolvability, and performance. It also provides an abstract model of how an ideal Web application behaves in order to maximize those beneficial properties.
You must remember REST is a style and SOAP is a protocol.
Most of REST's constraints are focused on preserving independent evolvability over time, which is only measurable on the scale of years. Most developers simply don't care what happens to their product years after it is deployed, or at least they expect to be around to rewrite it when such change occurs.
From Fielding dissertation
One of the major goals of REST is to support the gradual and fragmented deployment of changes within an already deployed architecture.
[...] a style is a named set of constraints on architectural elements that induces the set of properties desired of the architecture.
REST provides a set of architectural constraints that, when applied as a whole, emphasizes scalability of component interactions, generality of interfaces, independent deployment of components, and intermediary components to reduce interaction latency, enforce security, and encapsulate legacy systems.
REST is a hybrid style derived from several of the network-based architectural styles described in Chapter 3 and combined with additional constraints that define a uniform connector interface.
REST is defined by four interface constraints: identification of resources; manipulation of resources through representations; self- descriptive messages; and, hypermedia as the engine of application state.
Although REST interaction is two-way, the large-grain data flows of hypermedia interaction can each be processed like a data-flow network, with filter components selectively applied to the data stream in order to transform the content as it passes. Within REST, intermediary components can actively transform the content of messages because the messages are self-descriptive and their semantics are visible to intermediaries.
I describe the lessons learned from applying REST to the design of the Hypertext Transfer Protocol and Uniform Resource Identifier standards.
REST provides a set of architectural constraints that, when applied as a whole, emphasizes scalability of component interactions, generality of interfaces, independent deployment of components, and intermediary components to reduce interaction latency, enforce security, and encapsulate legacy systems.
Therefore, architectural design and source code structural design, though closely related, are separate design activities. Unfortunately, some descriptions of software architecture fail to make this distinction
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.
REST [...] allows information hiding through a generic interface to enable encapsulation and evolution of services, and provides for a diverse set of functionality through downloadable feature-engines.
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. [...] For example, the “authors’ preferred version” of an academic paper is a mapping whose value changes over time, whereas a mapping to “the paper published in the proceedings of conference X” is static. These are two distinct resources, even if they both map to the same value at some point in time.
- It provides generality by encompassing many sources of information without artificially distinguishing them by type or implementation
- It allows late binding of the reference to a representation, enabling content negotiation to take place based on characteristics of the request.
- 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).
Requests and responses have the appearance of a remote invocation style, but REST messages are targeted at a conceptual resource rather than an implementation identifier.
REST works well because it does not limit the implementation of resources to certain predefined models, allowing each application to choose an implementation that best matches its own needs and enabling the replacement of implementations without impacting the user.
About Uniform Rresource Identifier (Note that it rather identify reprensentations of a resource, not the resource itself. A content selection algorithm can be used to dynamically select a representation that best fits the capabilities of that client):
The definition of resource in REST is based on a simple premise: identifiers should change as infrequently as possible. [...] authors need an identifier that closely matches the semantics they intend by a hypermedia reference.
The most frequent violations [of REST] are in regard to the constraints on application state and stateless interaction.
For both frames and cookies [violation of REST], the failure was in providing indirect application state that could not be managed or interpreted by the user agent. A design that placed this information within a primary representation, thereby informing the user agent on how to manage the hypermedia workspace for a specified realm of resources, could have accomplished the same tasks without violating the REST constraints, while leading to a better user interface and less interference with caching.
For a distributed hypermedia system, component interactions consist of large-grain data transfers rather than computation-intensive tasks.
About architecture:
The goal of architectural design is to create an architecture with a set of architectural properties that form a superset of the system requirements.
An architectural style, as a coordinated set of constraints, is applied to a design space in order to induce the architectural properties that are desired of the system. By applying a style, an architect is differentiating the software design space in the hope that the result will better match the forces inherent in the application, thus leading to system behavior that enhances the natural pattern rather than conflicting with it.
keeping in mind that an architecture is the realization of an architectural design and not the design itself.
About evaluating the design of application architectures
Each architectural design decision can be seen as an application of a style. Since the addition of a constraint may derive a new style, we can think of the space of all possible architectural styles as a derivation tree, with its root being the null style (empty set of constraints).
If we understand the properties induced by each basic style, then traversing the derivation tree gives us an understanding of the overall design’s architectural properties.
About performance:
It is important to note that design considerations for optimizing latency will often have the side-effect of degrading completion time, and vice versa.
Code-On-Demand:
REST allows client functionality to be extended by downloading and executing code in the form of applets or scripts.
Hypertext = data-guided controls.
Steve Klabnik:
REST is not about exposing your object over the Web.
http://timelessrepo.com/haters-gonna-hateoas
Hypermedia Controls is the one that everyone falls down on. There’s two parts to this: content negotiation and HATEOAS. Content negotiation is focused on different representations of a particular resource, and HATEOAS is about the discoverability of actions on a resource.
“How do I version my API?” The proper way to do this is with the Accepts header, and use a MIME type like application/yourcompany.v1+json. There’s a great article about this by Peter Williams here
Wikipedia and rel attribute:
Standardized link relations are one of the foundations of HATEOAS as they allow the user agent to understand the meaning of the available state transitions in a REST system.
Using generic media types is perfectly legal but a bit silly. You are not really asking for any old XML document, but rather an XML document that has a quite specific schema.
Peter Williams when refering to Roy Fielding:
Hypermedia should be the core of our distributed application
About API versionning:
[...] don’t make backwards-incompatible changes, and if you do, change the media type.
As found in a comment on the Yahoo REST group (Not validated)
The application is defined by what the user agent(s) do. Not by what a media type spec says.
Howard Dierking
With REST you can change your application workflow without changing your client code.
The contract between client and the server is the uniform interface itself.
In REST, the network is not something to be abstracted away.
Remember the contract:
- Identification of resources
- Manipulation through representations
- Self-descriptive messages
- Hypermedia as the engine of application state
Self descriptive messages elements
- Status code
- Methods
- Control flow headers
- Metadata
Jan Algermissen
REST limits the possible contract changes to just two kinds: adding data or controls and removing data or controls from a message
Thanks for this comprehensive summary. I struggle to understand Roy Fielding’s REST alternative to HTTP cookies, § 6.3.4.2 ‘Cookies’ and § 6.5.4.1 ‘Application State in a Network-Based System’. How do you interpret it?