The real value of REST: Making the leap

REST is not an architectural style to undertake lightly. Understand the problem it solves, what gaps it covers, and decide if it's right for your architecture

One of the more reviled, misunderstood software architectures today, REST can turn a simple problem into a complicated mess. The fault lies not in the architecture itself, instead where and how it is applied. As REST at its core is simply a description of the architecture of the web, its ultimate merit can be seen seeing how far the web has scaled through its explosive growth.

Like many new ideas or concepts, it takes many iterations of applying that concept in a variety of areas and scenarios before its true areas of applicability emerge. In the first wave of enthusiasm, developers focused on simply escaping the complication of SOAP-based web services in favor for lighter frameworks and protocols. Today, most web services labeled "RESTful" do not follow the constraints laid out by the original definition of REST, but the term has become so widely used to describe generic web services that its original term has lost all meaning.

Instead of arguing about whether an API is RESTful or not, it's more valuable to focus on the original constraints and the problems REST is intended to solve. Most web services expose capabilities through JSON-based endpoints, returning data in a format easily consumed by Javascript-based client libraries:

GET /movies/12345

200 OK { title: "The Godfather" releaseYear: 1972 director: "Francis Ford Coppola" actors: [ ... ] }

For the vast majority of web service-driven applications, this level of detail is sufficient to build a functional, maintainable and resilient application. This is because of the nature of how most web applications are developed that take advantage of web services. For web services intended to be used solely inside a single application, where the API is developed inside the same source control repository, there is little need for the level of decoupling that all the REST constraints provide.

Change arises

Let's consider for a moment a client that is not owned by the same developers that expose a web service. This team wants to expose capabilities for others to consume, but want to do so in such a way that remains resilient in the face of change. For vanilla web services, this normally brings up the topic of versioning. In the previous example, suppose we want to add new information to our response, such as who produced the film, its box office draw, additional cast and crew. This sort of change could be accomplished by adding new fields, something nearly all clients could accept without breaking. What about modifying capabilities? Instead of a single director, we allow multiple directors?

We also make assumptions in our client consumers. What can I do with this movie information? Can I change it? Can I perform ancillary activities such as add a review, rate it, add comments, create a discussion? How do I see more movies by the director, actors, view sequels? In a normal web page describing this movie such as one found at, all of these are possible, but in our plain JSON payload, our message does not describe any of the possible actions I can take. It's a dead end.

Making the REST leap (or not)

The problems highlighted above are only truly problems if I am attempting to expose this API to users outside my system. In order to serve my clients effectively, I can take a few routes. The first is to go the full REST route, identifying gaps and modifying our message and protocol to adhere to the REST architectural constraints. This route takes a non-trivial work, both on enriching our server responses and on the consuming client. The work to extend our client should not be taken lightly - it is quite a bit more work to build a decoupled client that takes full advantage of REST.

The second, equally valid option is to supplement our API with documentation about capabilities. Instead of embedding this information in our message, we build out public documentation, examples, code snippets and more. This is the path that most APIs that label themselves "RESTful" take. Versioning is introduced in the face of breaking changes, and breaking changes are not lightly introduced. For many APIs, this is a perfectly acceptable solution. The problem space is well understood, and APIs rarely, if ever, change.

But sometimes change is inevitable, and we want to allow our client consumers to adapt to new/modified capabilities. In that case, REST is appropriate. In the next post, we'll take our original response and layer on more and more capabilities until we've completely fulfilled the original REST constraints with a decoupled client/server interaction.

Join the Computerworld newsletter!

Error: Please check your email address.

More about

Show Comments

Market Place