Working with APIs (part 1)

This is the first in a series of ProfHacker 101 posts on working with APIs. Coverage in this post includes an introduction to the concept of the API, why you might want to work with APIs, and what you will need to get started. Posts in the not-too-distant future will include practical examples both of pulling and pushing data from or through an API, and of course handling the results that are returned.

There is no single Application Programming Interface, nor is there a single programming language or method of access through that interface. The developer of a particular application or service purposefully creates a way for users to access the core functional framework or data stored within that service. For example, with Google Maps you can create custom maps including points on the map that contain additional information about the location; with Twitter you can archive search results or even tweet from a custom-built application; with WordPress, plugin developers can create scripts that enhance the underlying framework—the list goes on.

If your request is properly designed according to the API documentation for that application or service, then data will flow back to you through the same doorway. If your request isn’t properly designed, then imagine you’ve sent a scout through the doorway and, finding nothing in the room and, he returned back empty-handed, only to find a note stuffed in his back pocket that says “Hey Request Scout, you didn’t look in the right place. Sorry you missed us. Love, Data.”

So now that you know the concept of working with an API, why might you want to? The reasons for working with an application’s API are as numerous as an application’s users. Using an API you can begin to create a new user experience around the core functionality of the application (operational tasks). Or, you can leverage data already stored to produce reports or create an entirely different application (data manipulation tasks). The possibilities are endless, which probably makes this brief blog post a little maddening—that’s why we planned a series! But even if you think in terms of Twitter, the Twitter API is already in heavy use by developers worldwide.

If you think about the two broad types of tasks I just mentioned—operational tasks and data manipulation tasks—and you are in any way familiar with Twitter, you can begin to see how an API works. Every single Twitter client out there (some of which I’ve discussed before on ProfHacker) that is not the web interface at twitter.com uses the Twitter API. So, if you use TweetDeck or twhirl or Tweetie or whatever the client may be, those are instances in which those application developers have created their own operational tasks (wrapped in nice interfaces) based on the Twitter API and accessing all the data stored by Twitter (your account information, your friends, your followers, etc). Even if the top Twitter client is still the web (at 65%), 35% of all tweets are sent using someone else’s operational tasks built on top of the Twitter API. Similarly, applications that perform data manipulation tasks, such as archiving with Twapper Keeper or seeing real-time search results with Twitter Fall, or looking at Twitter visualizations such as Twistori and Social Collider, are accessing the Twitter API to retrieve that data.

A popular use of an application’s API is the use of the Google Maps API for data manipulation. Using the Google Maps API plus your own or third-party data to create interactive mashups is one of the “gateway drugs” of API scripting, because Google makes it very easy to work with their tools. The Google Maps Mania blog tracks all the Google Maps mashups it can find; here’s a mashup they just discussed about the Station Fire in California. Creating Google Map mashups are a great way to get your students involved in documenting the relationships between events they may be studying and where those events happened in the physical world—not just the world in their books.

How to get started working with APIs completely depends on what you want to achieve. Once you know what you want to do—for instance, do you want to annotate a map, or archive search data, or create a new interface to an existing service, and so on—you can narrow it down to a single application or service whose features or data you wish to leverage. After you determine if you’re going to work with Twitter, or Google Maps, or [insert other application API here], head toward the API documentation for that application or service. All (good) API documentation will have examples for how to complete specific tasks; you have to be able to conceptualize how those tasks fit together.

As far as technical specifications and technical knowledge, it really depends on what you are trying to achieve and with which service’s API. Almost certainly though, you will have to obtain an “API Key” or “Developer’s Key” for the API(s) you want to access. This key is an alphanumeric string that will identify your scripts or your own application when it accesses the parent application’s API. For any of you who are WordPress users, you might already have obtained an API key for WordPress if you have also installed the Akismet or WordPress Stats plugins. The API key is a way to register your installation of those plugins (or your own scripts) with the developers of the platform you are accessing.

Do you need to know a programming language, have a database at your disposal, or otherwise dip your toe into unfamiliar waters? It really depends. If you’re working directly with the Twitter API in a meaningful way, then yes you will need to be familiar with a server-side scripting language at least to the extent that I describe in this how-to post regarding archiving tweets. But the Google Developer Resources provide many ways of accessing the various Google APIs without knowing server-side programming. These access methods are based on query strings in a URL (which are themselves accessing the underlying API) and can be used for all sorts of things such as producing the lovely chart you see here.

Working with APIs can be incredibly creative and rewarding in the classroom; they can help your students become more knowledgeable not only about the subject matter they are studying (by working with it in different ways than simply consuming the words in a book) but about the processes through which others are able to feed information to them—and I’m not even mentioning the ways in which documenting APIs can find its way into the technical writing classroom.

In the next installment of this series, I’ll dive into the nitty-gritty of working with two different APIs to pull data—one that requires server-side programming knowledge and one that does not. If you have a particular example you’d like to see, let me know.