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:
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.
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 IMDB.com, 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.
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.