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.
Almost there
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?
But there’s no rush. Roy Fielding’s dissertation was published in 2001. Martin Fowler’s blog post, quoted above, appeared in 2010. Today, in late 2016, I can’t point to a single service or framework of Rails’ fame or ambition that is using hypermedia controls. The JavaScript development space is exploding with web, mobile, and desktop frameworks that all take REST at its second level as given. Maybe inside corporations or industry groups, there is progress, but I wouldn’t know. This is disappointing, because REST without hypermedia is hollow. Fielding, who coined the term to begin with, insists that hypermedia is a requirement for REST. After all, the Web has had it from the beginning, and it wouldn’t be the Web without it.
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.
Illustrative Examples
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.
The author who’s come closest so far to working out the practical bits for us mere mortals is Mike Amundsen, whose half-finished book RESTful Web Clients gives concrete (but incomplete) implementations of a To-Do service API and rudimentary JavaScript client. Amundsen has written quite a bit on REST over the last few years, and I hope he finishes the book soon.
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.
- Its clients would let the hypermedia controls in the API’s responses drive their behavior, just as human users follow links and fill forms in a website. This is different from the primary focus in most web service clients (which has launched a thousand JavaScript frameworks) on updating the HTML DOM when an in-memory object’s properties change.
- 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.
What now?
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?
- How would any of this month’s red-hot JavaScript client frameworks interact with a RESTful API? Where would things diverge from the current SOP of calling endpoints and deserializing JSON text responses? Would it be possible simply to drop in a different Ajax library, or enhance the jQuery that it seems like everyone uses? Would the non-http parts of a single-page app or other client-side application simply work the same way? Or would there be additional changes that would have to be made in the client app’s state management or even the UI it presented to users?
- 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 (
A,FORM,OL,UL,REL, andMETA) line up really cleanly with REST’s goals for content elaboration and communication of affordances. They should, after all: they are hypermedia controls meant for the browser user. It could be straightforward to adapt them for communication between software applications. One big benefit to using HTML this way would be the creation of an accessible version of your API, one that a user could consume with a web browser—no javascript needed so none of the accessibility challenges that still baffle developers.
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?