REST, RESTful and Architecture

A while ago I answered a question in Software Engineering of Stack Exchange which leads me to the post of today; a common misunderstanding about REST, RESTful and related architecture and design.

The answer can be read in the following link:

What is REST?

Rest is a client-server principle and it is not necessarily web, even when the most common representation is any HTTP service serving web pages. I don’t want to go into details about REST because it is very simple to find all sort of literature, blog posts, wiki pages and so forth related to that. I will only emphasize the principles:

  • Stateless
  • Cacheable
  • Uniform interface
  • Layered system
  • Code on demand (my less favorite principle by far)


A RESTful interface sits on top of REST using the same principles, but implementing verbs that represent operations on the resources. Operations on a RESTful interface will execute a verb on a specific resource and return a response code and possible a body. Everything is executed over HTTP.

Resources in a RESTful interface become more important, due to the fact we are executing operations the resource needs to be addressable and unique.

ROA = Resource Oriented Architecture

A well designed RESTful interface sticks to the ROA principles. This is the point where all these principles are combined to constitute an Architecture. ROA defines much better what a resource can be, how it can be addressed, uniqueness, principles, designs and so forth. RESTful is more ambiguous than ROA because it’s a set of principles, not an architecture.

ROA makes a very clear distinction of all sort of things that can constitute a resource such as:

  • A document
  • A version of the document
  • A language version of the document
  • The last version of the document
  • A search result
  • The list of items I normally buy in a store
  • My favorite products
  • My preferences

I emphasized these examples to show how an addressable resource doesn’t mean it’s always the same resource. For example, analyzing “the last version of the document” can yield different results every day I execute it, the document can be modified and returns a different output but it is still addressable and unique.

Another important principle of ROA is resources must be self-descriptive. A human might be able to infer easily what the resource is about. There are several notations and concepts to design, such as entities hierarchy, for example, the preferences of a particular user should be defined as:


Those principles might change based on system necessities but it is a good idea to read about them at least to form some opinion about them.


The biggest limitation I always found is practicability. A common example is search features. Following the principles our search should be addressed with something like:

GET /search/products?param1=value1&param2=value2....

Which is great from a formal standpoint. But imagine a search engine of a particular entity with 50 parameters, readiness gets complex and in some cases browsers might not be able to represent it. Those limitations are fading away but it is fairly complex to stick to the principles and keep system’s maintainability in some cases. We are always tempted (and many times it happens) to use a POST /search/products with a JSON/XML body. In theory, it violates addressability and RESTful principles (POST can only create entities and return responses according to it)


It is very important to differentiate principles, practices and architecture. In some cases we will only find guidelines or best practices. I cannot remember how many  times developers argue about some particular design guidelines which are only guidelines. As a general rule, it is important to know the theory but apply a pragmatic approach to design.

Design is very important anyways, there are a lot of APIs poorly designed in a way that emulate old RPC calls, RESTful is a good design, know the basis before starting your development.

Published by maxriosflores

Solution Architect for a decade. I designed, built and implemented software solutions for more than 25 years and every single day more interested on technology. I learned to code in a Texas Instruments with 16kb at 8 years old. I shared this passion with friends coding CZ Spectrums, MSX's and C64's. I worked in computers since my early 17's with super old tools like plain C and Quick Basic. I love math and computers as much as outdoors and family life.

Leave a comment

Your email address will not be published. Required fields are marked *