I’ve been interested in REST as a principle for Web service design for a while now. Rather than reimplement pre-WWW methodologies for network communication over the web, REST offers a way to use the power and resilience of the web itself to guide the way we develop applications. Ever since Ruby on Rails 1.2 brought “RESTful” into the vernacular of web developers, it’s seemed as though the triumph of REST was imminent. It’s seemed that way for a long time now, however, and I’m beginning to wonder whether we developers will ever find ourselves working with robust hypermedia formats, controls, and affordances as frequently as we work with JSON representations of CRUD operations. Has REST peaked in its degree of implementation and influence on developers? Is hypermedia too complicated or unnecessarily sophisticated for the future of applications that communicate over the internet? Are there market forces that discourage RESTful API design? Or is there still a RESTful future for applications that communicate over the Internet?
What am I talking about?
As youâ€™re still reading this post, I surmise you are a web developer, or you are familiar with the last several years of web development. So Iâ€™m not going to go into much detail about what it is, though I will make a few remarks so that you’ll have an idea of what I’m talking about and how I (probably incompletely) understand it.
REST is not an elevator-pitch idea. First, it stands for Representational State Transfer, a phrase which does not communicate its meaning immediately. Second, it springs from a dissertation, not a blog post or a motivational book. The dissertation, written by one of the architects of the modern World Wide Web, Roy Fielding, attempts to generalize a description of a system that could define a dependable, resilient, world-wide information network. So it’s not about the Web, but an abstraction the Web happens to implement. Third, REST is one of those ideas, like ‘organic’, to pick a possibly explosive example, that means different (and more) things to some influential people than to others. To a lot of people, REST means CRUD.
To describe what I think REST means, practically, for Web programming, I stand on the shoulders of giants and refer to The Richardson Maturity Model, as elaborated by Martin Fowler. If you don’t feel like reading that article, here’s my gloss. At the most basic level, a RESTful service exposes multiple endpoints, grouped around resources. At the next level, the service uses different HTTP verbs to communicate the nature of a request–is it safe, is it destructive, is it repeatable without additional effectsâ€”and depends on header information and MIME types to do content negotiation. This second level is where almost all RESTful services operate now. It’s where Ruby on Rails and the frameworks that it inspired still operate. It seems much better than the alternatives it has supplanted.
But there is another conceptual level: the addition of hypermedia controls which allow the service to communicate not only about resources, but about actions that may be taken. They add information about how the service itself can be used. To imagine the difference between level 2 and 3, imagine if the WWW did not have hyperlinks. To request a page in a web browser, you would have to type in the precise URL every time. Furthermore, imagine there were no forms. To submit information, you would somehow have to hand-craft a POST request to the server. That’s what REST level 2 is like. The hypermedia controls essentially provide the function of links and forms. That seems hugely valuable to me. I can’t imagine developers would not be rushing to take advantage of techniques that have powered the web for 25 years and made it a dominant global medium.
Where is everyone?
It may be that RESTful web services just aren’t necessary, and, like legions of other promising technologies, REST will simply be set aside for something perceived as simpler. The Web is a utilitarian place, and the simplest and fastest thing tends to gain widespread use. If there is no graspable advantage to using hypermedia, very few people will try to use it. It doesn’t matter that some people like me think REST is a model for services is elegant, or that we feel like it goes with the grain of the Web itself and therefore must offer tremendous advantages. Until lots of people demonstrably realize these advantages, it’s kind of academic.
Maybe the economics of web development oppose REST. The trend in development, which is another way of saying “programming that capital sources will pay for,” appears to be ever-slimmer layers of communication between server and client, with more and more custom one-off logic and functionality larding the client application. REST, with its emphasis on widely-shared formats and the discoverability of features, might not be a good fit for companies that want to monopolize the perceived value of their offerings. Maybe the World Wide Web is the only hypermedia application that can really function because it belongs to everyone and no one. Every potential hypermedia application that comes along now probably does belong to someone, and they don’t want to let everyone else play with it.
The misunderstanding (or incomplete understanding) of REST is a problem too. If you conceive of REST as just a way to manage a database, that REST actually stands for Create-Read-Update-Delete, then you may be inclined to drop it for something new, like GraphQL, that you think will â€œreplaceâ€ REST. If you havenâ€™t seen all of its promise, it wonâ€™t seem that impressive.
If you want to know more about REST as it is laid forth in Fieldingâ€™s dissertation, you should really set aside an afternoon, and read Fieldingâ€™s dissertation. It isnâ€™t that hard, and we are technical people, right? If you want a shorter explanation focused on whatâ€™s at stake, try out this blog post from Fielding on the subject of hypermedia.
Another great resource is Leonard Richardson’s talk from the 2015 RESTFest conference about the Library Simplified project and all the benefits it got from adopting an existing hypermedia syndication format, OPDS. Richardson highlights the disruptive potential of standardized hypermedia formats for API design.
Steve Klabnikâ€™s lamentably unfinished Hypermedia APIs book has a great sample chapter on affordances, or the functionality that hypermedia controls expose to the client. This again illustrates how different a RESTful API could be from what passes as RESTful right now.
What would RESTful look like?
- A truly RESTful service would couple its code to a published standard or to one or more content types, not to a list of URLs and some expectations about what hierarchical data the URLs return.
- The service’s designers would think of the application they were exposing as a state machineâ€”with, you know, states and transitionsâ€”that would communicate to clients what functionality was available from the service. This is different from the way most web developers think of APIs: as a way to stick data in a database or retrieve it.
That’s my lament for REST. You might be wondering whether Iâ€™m going to do something about it, or just complain. Well, Iâ€™m no expert on this stuff (not like Fielding, or Richardson, or Amundsen), but I do think there are some small steps that could be taken to illustrate untapped potential and win over more developers. I may be able to tackle some of them, if life permits.
- Rails 5.0 is intended to make it easy to develop an API, although it looks like the API implementation assumes youâ€™re going to emit vanilla, resource-focused JSON that is generated by enumerating Domain Objectsâ€™ properties (themselves often enumerated from database records). In other words, itâ€™s resource-focused, but it doesnâ€™t offer hypermedia controls, content types, profiles. Perhaps thereâ€™s a Rails-friendly way to create more RESTful API messages in a media format like Collection-JSON. Rails is still an easy way to stand up a non-trivial web service, and it seems like a good place to experiment with RESTful service development.
- It might be illustrative to take a widely-used public API, like githubâ€™s or iTunesâ€™, and work up what a hypermedia content-type for their resources would look like. These APIs currently communicate all of their information out-of-band and expect clients to know without guidance from the API which of a gazillion URL endpoints to call to get something or do someting. What if there were content types that encompassed the resources’ data and their relationships to each other, and that communicated the workflows available?
- One possible hypermedia format for RESTful services is good old HTML. The idea of just using HTML in an API is controversial, but the semantic tags already present (
If any of this sounds interesting, or if it sounds like baloney, or if thereâ€™s obvious stuff Iâ€™m missing, please get in touch. Iâ€™m @goodmike on twitter, and you can trackback to this post by linking to it from your own blog post if you want to extend or take issue with anything Iâ€™m saying. REST should make web service development easier and better, but it should also make the Web wider.
Can we get it done?