mca blog

I've held onto this blog post for a long time. I really don't like writing this one as it opens an entirely new avenue of study/debate the time for which I do not have right now. But, as there seems to be a new round of "Is your API RESTful" talk going around, I find I've had to cover material here too many times; I'm tired of repeating myself. So, here goes.

Very often (very often) I am asked to tell someone if their implementation is "RESTful", "is a REST API", is "RESTful enough", etc. Rarely am I asked to tell someone if their chosen architectural style is appropriate for the problem at hand. IOW, people want to know if the work fits a label invented over a decade ago by a PhD candidate in his dissertation.

Almost everytime the answer is the same: "NO."

This answer makes some people sad. Some angry. Occasionally, some people ask questions about why I gave the answer I did. Rarely, do people ask me if the implementation is appropriate for the intended use.

So Let's Assume you Really Want to Know the Answer

I know there is a group of folks who just don't want to talk about this idea of actually analyzing and designing network-based architectural styles. They prefer instead to write good code, release it, and support it. That's great. I love that. I also know that some folks write dissertations about this stuff, apply this type of thinking in their daily work, and find value in contemplating the abstractions we each employ every day. I love that, too.

If you don't like to talk about analysis and design of network-based architectural styles then you can skip the remainder of this post.

Is This Appropriate?

The following exercise does not make any judgment about whether the style employed is *appropriate* for the task at hand. IOW, it's is possible that an accurate implementation of Fielding's style is *not* what is needed for the task at hand (i.e. the architect picked the wrong style for the job). If you want to judge whether the style is appropriate for the task, that is a completely different process. Fielding lays out his approach for defining a style that matches the problem space in Chapter 4 of his dissertation.

If what you want to do is make a judgment about whether the target implementation is *appropriate* for the task at hand then you can skip the remainder of this post.

Does this Implementation Exhibit Fielding's REST Style?

If you want to make a judgment on how much an implementation adheres Fielding's REST style, you need to use his measure. Fielding identified just how this style of his should be defined and what criteria should be used when evaluating this style.

If you plan on using some criteria other than that which Fielding used when inventing the named style (REST) then you can skip the remainder of this post.

A Set of Constraints

Fielding states " ...an architectural style is a coordinated set of architectural constraints that has been given a name for ease of reference". He then lays out his set of chosen constraints for a style he names " REST". It's important to decide if you accept this assertion.

If you think an architectural style is something other (or more) than "a set of architectural constraints" then you can skip the remainder of this post.

Have your Definitions Settled First

Fielding's dissertation does a good job of describing the top six (primary) constraints ( Client-Server, Stateless, Cache, Uniform Interface, Layered System, Code-On-Demand). It is usually easy to find shared understanding of these constraints. The four sub-constraints Identified as the "four interface constraints" (identification of resources; manipulation of resources through representations; self-descriptive messages; and, hypermedia as the engine of application state) are only partially identified in the text. Resource Identifiers and Representations are well-defined, but the remaining two ("Self-Descriptive Messages", and "Hypermedia....") are not easily found in the original text.

Fielding added what is generally accepted as a sufficient definition of the Hypermedia constraint in his 2008 blog post " REST APIs must be hypertext driven". I have yet to find a definitive definition for the "Self-Descriptive Messages" constraint. However, the following quote from the dissertation is most often used as the definition : "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." This needs work as the word "standard" here is insufficiently defined.

Before attempting to determine if some implementation exhibits Fielding's REST style, be sure you have clear definitions for all ten constraints. Failure to have this will doom your efforts.

If you don't yet have your definitions clear then you can skip the remainder of this post.

Are You Ready?

If you agree that:

1. This work is *not* about deciding if an arch style is appropriate for the task at hand
2. Fielding's criteria are the only ones to use for this evaluation
3. The criteria to use is a set of constraints
4. You have wide agreement on the definition of all ten of Fielding's constraints

Then you are ready to begin.

Show Me All Ten

All that remains is to identify each of Fielding's ten constraints (six primary, four secondary) within the target architectural design. IOW, show where each of his ten constraints are adhered to in the implementation. If the implementation does not exhibit all ten (well nine, since Code On Demand is an optional constraint) then the implementation does not exhibit Fielding's REST style, but it *does* exhibit some other (likely un-named) style.

And Here Comes Trouble

This last step is not all that difficult. It is the previous step (agreeing on defintions) that, to this day, remains ellusive. Too many people carry around (and pontificate upon) mistaken definitions of Fielding's REST style. Those who do this not only embarass themselves and mislead others, they hamper the efforts of those trying to get to the end of this single line of reasoning.

In the end this is not a very big deal. We ask these types of questions quite often in life. Is this building in the Gothic style? Is this a pointillistic painting? Is this chair Swedish modern? What are the criteria for deciding these things? Can I just make my own up? Can I even tell the difference between medieval and modern art?

Is your app RESTful?