The Principles of Web API Usage

Not too long ago, I wrote an article about "The Increasing Importance of APIs in Web Development." As a follow-up, today, I'll cover the basics of using Web APIs.

Before we begin: this article does not detail the process of API design or development. That's for a different article!

Basic Principles

There are a handful of basic principles that should be followed when using Web APIs:

Build applications that are social and engaging
Give users choice and control whenever applicable
Don't surprise, mislead or confuse users
Don't create or distribute spam; always encourage genuine communication
Respect the user's privacy
Be a good partner to Web API providers

Most of these guidelines are listed in the API "terms of service" for Twitter and Facebook, but can be applied to all Web APIs.

Evaluate Your Coding Skills

There are thousands of Web APIs available and most can be either integrated into a website, or to create a mashup. Some Web APIs are fairly simple and require minimal coding skills to implement, while others can be extremely complex and require advanced programming skills.

The programming language you use to integrate a Web API into your website certainly depends on which ones you're most comfortable with. You'll find that many Web APIs, such as Flickr and Last.fm offer language specific toolkits.

Read the Terms and Conditions

Every Web API has specific terms regarding its usage; so it's incredibly important that the "terms and conditions" are read carefully. They will detail many aspects of Web API usage, including:

Copyright Infringement
Logo Identity, Branding & Trademarks
Content Usage & Guidelines
General Restrictions
Usage Limitations
Use of cache files
Privacy Policy

There may be additional "terms of use" information located on separate web pages. For example, there are "Display Guidelines" described in detail on separate web pages for Twitter, Foursquare, LinkedIn and Facebook.

Read the Documentation

Most Web APIs have detailed documentation available, which usually contains important information such as:

Features list
Available data formats
How to request an API key
How to use authentication (OAuth)
Examples of API calls & data requests
Tutorials and sample code
API reference page

Use the Latest Version / Versioning

Some Web API Providers recommend the use of a versioning parameter in the API call.

Many Web API providers frequently release new versions of their APIs. These new releases may include the following:

Added functionality
Increased speed
Improved stability
Improved accuracy
Bug fixes

Some Web API Providers recommend the use of a versioning parameter in the API call. Foursquare for example, accepts the param "v=YYYYMMDD" in API calls. This parameter will help indicate that the client is up to date as of the specified date.

Periodically Check the Change Log

It is a smart idea to periodically check the change log (if one exists) when using Web APIs. Many popular APIs have change logs available, such as Facebook, Google Maps, Google Charts and Foursquare.

Plenty of API providers offer additional ways to keep track of their API revisions:

Subscribing to the API Developer blog
Following the API on Twitter
Joining an API User Group
Subscribing to an API email newsletter

Usage Limits

Nearly all web APIs are subject to rate limits; some API providers even charge fees if a user exceeds the API rate limit!

Usage of most (if not all) APIs is subject to rate limits and each API provider has its own API rate limiting policy. Some API providers even charge fees if a user exceeds the API rate limit! Google recently introduced a new rate limiting policy for the Maps API which includes usage fees. Google has also provided additional details regarding the Maps API usage limits on their Geo Developers Blog. Here are links to rate limiting information for a few of the more popular APIs:

It's incredibly important that you not abuse the API. If you're website is making an API call for every single page load, and for every single visitor, ask yourself, "Why"? Implement proper caching techniques to improve your website's performance, and potentially save money.

Caching Data

Using a "cache file" will prevent problems with API Rate Limiting.

Using a "cache file" will prevent problems with API Rate Limiting. In the Nettuts+ post "How to Create an Advanced Twitter Widget,", there are instructions on how to create a PHP "cache file" script. This script retrieves the Twitter API "GET statuses/user_timeline" information and stores it in a "TXT" file located in a cache directory on the server. This script can be easily modified to work with most APIs. All you would have to do is change the txt file name and the API call. Note that the call in the script retrieves the data in JSON format.

It is important that you read the APIs "terms of use" for any reference to using cache files. For example, the Amazon Product Advertising API has restrictions on caching. Facebook recommends that if you use caching you should try to keep the data up to date.

Data Formats

The two most popular data formats for Web APIs are XML and JSON.

The two most popular data formats for Web APIs are XML and JSON; many providers offer both formats. However, JSON has become so popular among web developers to the point that some API providers, such as Foursquare, Twitter and Google+ offer the JSON data format exclusively.

API data formats are covered in detail in a previous post.

Sign-up for the API

Most API providers require users to sign up for a user account and/or an API Key. For example, Google asks its users to request an API key here. This is usually a fairly simple process and should only take a few minutes to do. You may also be asked to use a developer/application ID when using an API.

OAuth Token

Many APIs require the use of OAuth for specific API functionality.

OAuth (Open Authorization) is an open standard for authorization that allows users to share data and/or files stored on one website with another website.

Many APIs require the use of OAuth for specific API functionality, such as logging in and out of an application. The Google+ API requires ALL API calls to use an OAuth 2.0 token or an API key. Google recommends using OAuth 2.0 as the authorization protocol for Google APIs. Other examples of APIs that require the use of OAuth are LinkedIn, Twitter and Foursquare.

API Calls

An API "call" needs to be used in order for your website application to access a Web API. Depending on the type of application you are creating, you may need to use multiple API calls. Most APIs can be used with a variety of programming languages. The call may need to be modified for different programming languages. For example, in the tutorial, "How to Create an Advanced Twitter Widget", a PHP "cache file" script is created using the following Twitter API call:

http://api.twitter.com/1/statuses/user_timeline/twitter_screen_name.json?count=3&include_rts=true&include_entities=true

If you're using JavaScript or jQuery instead of PHP, the call will need to be changed to:

http://api.twitter.com/1/statuses/user_timeline/envatowebdev.json?count=3&include_rts=true&include_entities=true&callback=?

When using JavaScript or jQuery, "&callback=?" needs to be included in the API call, but if using PHP, it needs to be removed or the data will not be generated in a valid JSON format.

Test the API Call

There are several API testing tools available to help you test your API calls:

Platform Status

If you are having unexpected problems with an API, some API providers like Foursquare and Twitter offer platform status updates on status blogs.

Facebook offers a nice "Live Status Tool" that includes:

Current platform status
Issue history
Average API response time chart
Error count chart

Twitter also has an up to date "API Status Page" that includes:

Known hot issues
Recently closed issues
Live Current Performance and Availability Status
Performance and Availability History

Conclusion

Web APIs are becoming increasingly important in web development, and their popularity and usage has increased exponentially in the past few years. Hopefully, this article has detailed the basics of using Web APIs. If there are additional notes that I have not included, please mention them in the comments.

HIGHLIGHTS OF THE DAY