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.
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.
Sign up for Computerworld eNewsletters.