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 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:

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

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


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.

Related Posts
  • Code
    Android SDK
    Using New Relic to Monitor Your Android AppGetting started new relic retina preview2
    In the last two years, New Relic has focused hard on building out a solution for monitoring the performance of mobile apps. In this tutorial, we will look at how you can start using New Relic to monitor the performance of an Android application.Read More…
  • Code
    Creative Coding
    How to Implement Post Status Transitions for Custom Web ApplicationsCustom post status 400
    WordPress uses posts and pages to provide the dynamic content for applications. The introduction of Custom Post Types has increased the possibility of developing complex applications with WordPress. Generally, normal posts go through a well-defined workflow, before they get published on the website or on the application. During this workflow, various statuses are assigned to posts and handled internally by WordPress. Post statuses can be used as a powerful technique for managing status in a custom web application. In this article, we are going to discuss how to use WordPress custom post statuses and transitions to build applications which go beyond the conventional websites or blogs. Do you have experience in working with custom post status transitions? All of you are welcome to discuss your experiences.Read More…
  • Code
    iOS SDK
    Accessing Google Services Using the OAuth 2.0 ProtocolGoogle oauth@2x
    This tutorial will dive into implementing Google Services using the OAuth 2.0 protocol. Read on!Read More…
  • Code
    OAuth 2.0 - The Good, The Bad & The UglyOauth retina preview
    In a world dominated by social media, it's hard to not come across a client application which you have used to access restricted resources on some other server, for example, you might have used a web-based application (like NY Times) to share an interesting news article on your Facebook wall or tweet about it. Or, you might have used Quora's iPhone app that accesses your Facebook or Google+ profile and customizes the results based on your profile data, like suggesting to add/invite other users to Quora, based on your friends list. The question is, how do these applications gain access to your Facebook, Twitter or Google+ accounts and how are they able to access your confidential data? Before they can do so, they must present some form of authentication credentials and authorization grants to the resource server. Read More…
  • Code
    Creative Coding
    Building a WordPress-Friendly API Wrapper: FoundationsBuilding a wordpress friendly api wrapper
    When building a web site or web application, it's a pretty common requirement that you might need to pull in data from third-party site or application. If that site or application has an API, this is an excellent way to obtain the data needed. So, let's take a look at how to do this with WordPress.Read More…
  • Code
    On Working with Web ServicesWeb services preview
    This article is an exploration of web service protocols, common data interchange formats, and best practices. If you're interested in creating performant mobile applications that connect to the web, read on!Read More…