RESTful Web APIs

Chapter 2. A Simple API

In Chapter 1, I showed off a very simple microblogging website located at http://www.youtypeitwepostit.com/. As it happens, I’ve also designed a programmable API for this website. You can see it live at http://www.youtypeitwepostit.com/api/.

The ideal API would have the same characteristics that make the World Wide Web easy to use. As a developer, you would be able to figure out how to use it, starting with nothing but a URL you saw on a billboard.

Let’s spin out that fantasy to see how it would work. First, you would have your programmable client make a GET request for the billboard URL—the equivalent to entering that URL into your web browser’s address bar. Your client would take over from there, examining the response to see what the available options are. It would follow links (not necessarily HTML links), fill out forms (not necessarily HTML forms), and eventually accomplish the task you set out for it.

This book is not going to get us all the way to that goal. There are problems I can’t solve with a book: problems surrounding the absence of standards, problems with the current level of tool support, and the brute fact that computers just aren’t as smart as human beings. But we can get a long way toward that goal—a lot further than you may think.

As I said, there is a real microblogging API at http://www.youtypeitwepostit.com/api/. If you’re feeling adventurous, go ahead and write some code to do something with that API. See how much you can figure out, ...