Create More Web

October 20, 2015Dan Yoder

I’ve never had any interest in being a REST or HTTP evangelist. However, I believe that the Web, and the Internet upon which it stands, are possibly the most significant technological developments since the printing press. That’s why the Web-is-broken meme bothers me so much. The Web isn’t broken—it’s better than ever. It isn’t perfect, but I don’t believe that the answer is to go back to the world of proprietary islands of technology. However, the Web’s connection to the REST architectural style wasn’t always obvious to me. In fact, until recently, I couldn’t have explained it to you.

Why Do I Care?

After all, you can use HTTP without satisfying the REST constraints. Of course, the more you fully utilize the protocol, the more you end up satisfying REST constraints, because the design of the HTTP is the basis for them. But that is still fundamentally circular reasoning. Of course, as protocols go, HTTP has been a epoch-defining success. Which certainly suggests it is worthy of study. But still doesn’t answer the question. Why does the REST style matter so much? Why is it so important to fully utilize the HTTP protocol? Why have we found it so hard to resist spending our time explaining it? Or developing tools, libraries, and frameworks for it?

An Epiphany

A recent interview with Roy Fielding, the principal author of the HTTP specification, and the creator of the REST style, supplied me with the answer.

REST is still my advice on how to build an application for the Web in a fashion that is known to work well over time and known to create more Web as a result (more addressable resources).

The crucial phrase here is create more Web. If you believe the Web is a tremendous advance, (the greatest advance since the printing press), naturally you are in favor of creating more of it. In particular, the Web is one of those technologies that benefits from network effects.

For example, I just now linked to a Wikipedia entry on network effects. I couldn’t do that back when encyclopedias were DVDs sold commercially, and which you might not have purchased. The existence of that Wikipedia entry adds value to my blog post.

More generally, the more of the Web I link to from my post, the richer it becomes. In turn, this richness is what drives people to use the Web instead of something else. They see something of interest in their feed and they can click on it to find out more.

And this creates an incentive for people to make their content accessible on the Web. To create more Web. And so on.

What If…?

This is why designing APIs in terms of resources is so valuable. We tend to think of APIs as being distinct from Web pages. And that becomes a self-fufilling proposition. We create APIs that employ HTTP as mere transport. Sometimes they look more or less like glorified RPCs. Sometimes they look like object-oriented RPCs. Sometimes they look like database queries. And we say, you see, APIs are not like Web pages. Which is to miss the point entirely.

The question REST is asking is, what if they were?

If APIs were like Web pages, they would create more Web. Which, as we’ve already seen, makes the existing Web better.

Creating more Web with your API takes more work. Our libraries and tools can make this easier, but we have a long ways to go. If we work together, we can reduce the burden on individual developers and make creating more Web the default.

But if, instead, we insist on discarding and discrediting HTTP, the world’s most successful application protocol, and inventing our own specialized variants, such as Relay or Falcor or JetStream, we’ll never get there. Network effects for an API ecosystem can never accumulate.

Yoder’s Tenth Law?

As it happens, REST and HTTP also codify a great deal of learning from earlier efforts to build distributed systems. We’ve already tried RPCs and object-oriented RPCs and query languages. Perhaps there is a reason HTTP worked so well. Perhaps we learned from past mistakes. Perhaps you can learn from them, too. I like to apply Greenspun’s Tenth Rule to HTTP:

Any sufficiently complicated C or Fortran program API contains an ad hoc, informally-specified, bug-ridden, slow implementation of half of Common LispHTTP.

Don’t Break The Web

But I’ve come to realize it isn’t the architectural benefits that have inspired me to evangelize REST and HTTP. It’s the intuition that, with each API we build, we can create more Web. We’ve made a nice start of it. It’s amazing that APIs are even available on the Web to begin with, regardless of what idiom they employ.

But what we’re doing is reminiscent of the early days of Web sites, when developers would routinely “break the Web.” For example, you broke the Web if the back button didn’t work in your Web app. Or maybe a better analogy today is a Web application that isn’t responsive. REST provides you with guidelines that not only encapsulate best practices for building distributed systems, but which ensure that you don’t break the Web with your API.

Give Something Back

If you don’t care about the Web, if you don’t think creating more Web is valuable, if you don’t think perhaps that’s a good way to give something back, for all that the Web gives you, then obviously you won’t care about creating more Web. But if you care about the Web, strive to create more of it. And try not to break it in the process. And that’s what REST and HTTP are there to help you do.

One API, One Vote

Your choices affect all of us. Each decision to create more Web is one more vote for a free and open technology, and, ultimately, for a free and open society. And each decision to forego that technology is a vote to go back to the days when each vendor had their own proprietary islands of technology. It’s just one vote, sure, but, in aggregate, it makes a difference. That’s why we have the Web in the first place. Because developers like you decided to make it.

Maybe we have enough Web. Maybe it’s okay if APIs aren’t more Web. But maybe the Web we have is only half, or a quarter, or an eighth, of what it could be…

And I’d like to see what that Web looks like.