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.

But during the last few years, a more informal sort of API has emerged. Sometimes it's based on XML, but more often it's based on JSON, the "JavaScript Object Notation" format that works not only with JavaScript, but with a wide variety of other languages as well.

(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.

  • To allow your own application to access its own data via Ajax calls. When you make a JavaScript call in the background using Ajax, you most likely will want to make use of an API call, receiving XML or JSON, rather than HTML that requires further parsing.

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.


Comment viewing options

Select your preferred way to display the comments and click "Save settings" to activate your changes.

At a minimum, I would want

Tony lincle's picture

At a minimum, I would want the box to say "Live Data", Some of the more handy ones will scan the truck, record the data and download it to your computer. Many pull data from the trans, ABS, and other systems.
Truck Adblue Emulator for IVECO


qswatches's picture

In the winter, it's quiet, everything seems to be to the original state, as the time to stop down. But it is also and such rise, and seem to be pregnant with new life.rolex daytona & celine bag 2012

Traditional Chinese clothing

Anonymous's picture

Traditional Chinese clothing is usually worn loose and comfortably so as to not get in the way of work and daily activities. An exception to this in ancient times was footwear. It was considered beautiful for women to have exceptionally small feet, especially during the Sung Dynasty of the 1100s, and thus the feet of girls were tied tightly in bandages until the bones were broken and their feet were curled almost in half. Chinese Fashion

django apis example

kiddhustle's picture

Nice article that gave me a refresher on how a restful api should be structured.

Now are there any examples/ codw snippets showing how an api can be constructed in django? Currently looking at getting started with framework but I have no experience as yet.


Johanna's picture

RSS Feeds are indeed not geeky, but they are a bit old, nowadays people connect everything through API's, not through RSS feeds (like prepaid-mobiel.nl ). Welcome to 2012.

absolute REST example?

eMBee's picture

how would a search look like if you follow the REST absolutism you mentioned? i am only starting to look into REST and i can't even conceive why using actions in the url would be a problem. how do you do that then?

what about a resource like /airplanes/523/passengers
or /people/2341/address ?

wouldn't that be the same thing?

as for your routes example, how do the resulting urls look like?


and are those good or bad examples for a REST api?

greetings, eMBee.

Web APIs

Ed Carp's picture

This is what web services are for, and they've been around for a long time. There's nothing new here - output from wherever, wrap XML or JSON or even CSV text, ship it off to a consumer. Consumer strips off the JSON/XML/CSV and does whatever it wants with it. Pretty straightforward, actually.

I'm not sure why the author used a few thousand words to describe what I just did in less than 100. More words isn't necessarily better, unless you're getting paid by the word!

Well, it's not all about data

Ayesh's picture

Well, it's not all about data output. Client can send data to server, server and client can authenticate each other, and there are many actions. Yes it has been there since a long time but it's not all about data output. It's 2012 and rss feeds are no longer geeky.