If you're creating Web apps, you're designing APIs. Here are some things to keep in mind before you begin.
The Web was designed for people. When Tim Berners-Lee created the trio of standards that make up the Web—HTTP, HTML and URLs—the intention was for people to browse Web sites, submit information to them and be at the heart of the experience. But for some time now, the notion of the Web as a set of sites that people browse has been somewhat untrue. True, hundreds of millions of people visit an equally large number of sites each day; however, more and more of the visitors to sites aren't people, but programs.
Some of those programs exist to collect information on behalf of other systems. For example, when you search the Web using a site such as Google, you're obviously not searching through all of these sites in real time. Rather, you're asking Google to search through its massive index—an index that it has created and updated via its "bots", programs that go to a Web site, pretend to browse as a person, and then track whatever they find.
But more and more, the programs that are visiting sites aren't doing it on behalf of search indexes. Rather, they're doing it on behalf of...well, on behalf of themselves. Computers exchange information via the Web, using a variety of protocols and data formats. Native apps on mobile devices are using the Web behind the scenes to query Web applications. And, even those Web applications using Ajax are interacting with a Web site without directly being asked to do so.
This represents a massive shift in what Web applications are doing. No longer are we just producing HTML for users (and search bots). Now, we're producing output that's meant for programmatic consumption—and in many cases, the same people are writing the client and server sides. Sure, we could use "scraping" techniques to retrieve the HTML and search through it, but why do so? If we already know we'll be sending data to a program, there's no reason to send HTML. Rather, we can send it in a more program-friendly data format, without all the bells and whistles that people require.
When such use began, people made a big deal out of it. This trend was known as "Web services", and a lot of companies—most prominently Amazon—jumped on them, describing all sorts of standards, from XML-RPC to SOAP to WSDL. These protocols are still used, especially by large-scale enterprise applications, to communicate with one another.
(By "more informal", I don't mean that it's not useful or that more formality is needed. I'm merely referring to the fact that it requires coordination between the client and server software authors, rather than adherence to a specification document or established protocol.)
This month, I'm looking at these sorts of APIs—why you would want them, the different styles you can use in designing them, and then how to access and use them.
Why an API?
If you're running a Web application, you probably will want to provide an API at some point. Why? Well, there are a number of reasons:
To allow your users access to their data via third-party applications. Consider how many third-party Twitter clients exist, all of which use Twitter's API, rather than the Web site. The same is true for Amazon and eBay, among others, which allow users to access their catalog data and even execute sales, all via the API.
To allow mobile app developers to access your site. Mobile apps—that is, those running on such operating systems as Android and iOS—often send and retrieve data using HTTP, providing their own front end, in what we might consider a "domain-specific browser", albeit with a non-Web interface.
I'm sure there are additional reasons for providing an API, but even one of these might be a compelling reason in your case—and two or three of them might apply as well. There's also an element of customer openness and trust that comes with an API. I'm much more likely to use a Web application, particularly if it's one for which I'm paying, that provides an API to some or all of its functionality. Even if I never end up making use of it, I know I can do so potentially, which gives me a feeling of being a potential partner of the application's authors, rather than a simple user.
The above also demonstrates that even if you never plan to open up your API to the outside world, it might still be in your interest to design one. Indeed, I've recently heard several experienced Web developers argue that a modern Web site should not be designed as a set of pages, with the API tacked on as an afterthought, but rather as a set of APIs, which can be accessed via a mobile app, a remote client application, Ajax calls or a client-side framework, such as Backbone. In other words, first you establish your APIs, and then you get to work writing applications that use those APIs.
In many ways, this is an attractive thought, one that has the potential to make applications cleaner and easier to write and test. After all, the idea behind the MVC (model-view-controller) paradigm is to separate the different components, such that the business logic has no interaction with the interface presented to the user. MVC-style Web frameworks, such as Rails and Django, encourage this separation, but creating an API makes the distinctions even sharper.
Reuven M. Lerner, Linux Journal Senior Columnist, a longtime Web developer, consultant and trainer, is completing his PhD in learning sciences at Northwestern University.