At a recent conference, I found myself once again in a conversation about the meaning of the term REST. I’ve had this conversation so many times, that I tend to forget that not everyone has heard my take on the subject. The conversation ended with a “you should blog that…”.
Most developers are aware that REST is one of those terms that means different things to different people. Lots of key presses have been wasted arguing about what is and isn’t RESTful. I’m going to try and avoid that trap by making a particularly silly comparison to demonstrate why we should care about accurate use of terminology.
Constraints
The term REST has some similarities to the term “Chocolate Chip Cookie”. A chocolate chip cookie is defined by two primary constraints. It must be a cookie and it must contain chocolate chips. There is no single official chocolate chip cookie recipe. There are hundreds of different recipes, but the end result is always a cookie with chocolate chips in it. More importantly, kids love them.
The problem developers have with REST is that there is no single recipe for “how to do REST”. Developers like very prescriptive guidance on how to achieve a goal. The definition of REST simply provides a set of constraints and leaves out the details.
Desired Effect
When you are planning a birthday party and decide to buy some Chocolate Chip Cookies, you are not making that decision because you know Chocolate Chip Cookies contain flour and butter, but because you know kids love them, and you want the kids to be happy.
The REST constraints were chosen because they evoke certain characteristics in the systems that follow those constraints. You choose to follow REST constraints because you want those desired effects.
Sometimes Oatmeal cookies are better
When taking kids on a long car ride, especially in warmer climates, chocolate chip cookies are not always the best choice for snacks. Lots of kids like Oatmeal cookies too and they don’t make a mess of your back seat. It is the effect that is important, not the ingredients. You select the type of cookie that has the characteristics you desire.
Complying with the REST constraints requires a certain amount of work. Maybe you don’t need all the characteristics that a REST system exhibits, or maybe you need additional ones.
False Expectations
However, if you tell your birthday party guests that they are going to get chocolate chip cookies, and you switch the chocolate chips for raisins, you are going to have some confused and upset kids.
This is the key point of the REST naming debacle. Calling something REST that doesn’t conform to the constraints defined by REST is just a source of pain and confusion. Some people argue that the popular use of the term REST is simply a subset of the constraints. People have even tried to name these different sets of constraints: Hi-REST & Lo-REST, Fielding’s REST and Pop-REST. None of these distinctions have really taken hold.
Rogue Constraints
Imagine how someone would be ridiculed if they came along and said,
our cookie making machine produces square cookies therefore we declare that chocolate chip cookies must be square.
Or,
our chocolate chip cookie recipe contains pecans and they taste great, so we believe it is a best practice for all chocolate chip cookies to contain pecans.
Unfortunately, this has happened to the term REST. For a variety of different reasons, new constraints have been invented and attributed to REST. Sometimes, it is because someone believes the new constraint is a “best practice”, or often it is due to some framework limitation.
Land of confusion
The end result is many different definitions of REST. There are thousands of recipes for making chocolate chip cookies, but the basic definition of what is a chocolate chip cookie remains the same: cookie + chocolate chip.
The term REST should tell me that a system uses a layered architecture, uses caching, has a client-server architecture, interactions between the client and server are stateless and each layer applies the rules of the uniform interface constraint.
Today, the term REST doesn’t guarantee that any of these constraints are being respected and makes the term fairly worthless in technical conversations. The term HTTP API is much more accurate when describing most of today’s Web API. Many of the core REST community have resorted to using the term Hypermedia API to describe an API that actually conforms to all of the REST constraints.
There is a point where all metaphors break down, and the difference between chocolate chip cookies and REST is that you can do a web search and easily find a recipe to make a great tasting chocolate chip cookie. Unfortunately, you can’t do the same with REST due to the watering down of the term.
Let’s move on
It is an unfortunate state of affairs, and one that is likely never to be resolved. However, as long as you understand where we are and how we got here, we can move forward, get some real work done, stop debating what it means to be RESTful, and try not to make the same mistake with the next technical noun that comes along.
Image Credit : Cookies https://flic.kr/p/83Wef5
Image Credit: Kid with cookie https://flic.kr/p/dMNwWR
Image Credit: Birthday Party https://flic.kr/p/6D1ag1
Image Credit: Messy Face https://flic.kr/p/PVrds
Image Credit: Unhappy kid https://flic.kr/p/i8SrkX
Image Credit: Land of confusion https://flic.kr/p/5eLaX7