Do a search on the internet and you will find all sorts of information about the best practices for how to create an API, but very little for how to use an API in your application/site. After years of wrangling all sorts of APIs including social and mapping, here are a few things to consider when making that first step into the wide world of APIs.

Know the Terms and Conditions of the API

Not all terms and conditions are created equally. Get familiar in that ‘invading someone’s private space’ type of way with the terms and conditions of the API to be used. Terms and conditions cover topics such as data privacy, commercial use and restrictions, branding or display guidelines, data cacheing, and downtime clauses. These points alone, should govern the approach to working with an API.

100% Uptime is not an API reality

We’ve all witnessed the famous Twitter fail whale. The reality is, there is no such thing as having 100% uptime when dealing with APIs. Many APIs list a downtime clause in the terms and conditions. They make their best effort to keep the API healthy, but its truly an “as-is” agreement. For most people who are using the APIs with a standard type of access ( no special agreements or non-paid ), this is something that needs to be considered.

Putting all your eggs in one basket – to make an API call and assume that it is going to be up all the time, is a dangerous thing. Have a plan B. This will likely mean cacheing API calls, but at the very least, should account for this edge case and handle accordingly from an interface perspective where the user can be notified.

APIs Can and Will Change

Many have felt the pain of a change made in the Facebook Graph API that broke the past two years worth of projects. There is the possibility that a minor change might occur, and with a platform as immense as something like Facebook, it is bound to happen. Not much can be done here, you can’t plan for these changes, but often you can anticipate them as they are frequently documented and announced.

Most of the major APIs have really great documentation, support forums and a developer blog where these type of changes/fixes are posted and discussed. Make this a first stop before automatically assuming an untouched codebase magically changed on its own. This should be discussed with clients to prepare them for the possibility of future fixes or maintenance that may or may not currently be in the scope of work. A client will immediately come running to you as you built it, so you must have broke it.

Most APIs also document their roadmap. Keep up to date on these, as functionality currently utilized could be deprecated in the future.

Rate Limiting

APIs often enforce a rate limit to determine use and ensure the health of the service. Simply – a rate limit is the number of times data can be requested from an API within a certain amount of time per user / IP etc. To make things a bit more complicated, often these rates change on the endpoint ( type of data ) or endpoint grouping being accessed. For example, most GET requests for Twitter are rate limited, where POST requests are not. Sometimes the limit is determined by IP .On occasion, some APIs will increase the rate by request. Rate limits are not standardized in the least, so familiarizing yourself with the API documentation and terms of use will help clarify that specific APIs’ rules.

Rate limiting information is often made available by many APIs in custom headers found in the response.This may include things like how long before the rate limit is reset,the current rate limit, or even the number of calls left before hitting the rate limit. Developers can take advantage of this information to create smarter approaches around data requests.

Cacheing Data

API requests are expensive. When possible, it is a good idea to cache data. Refer to the terms and conditions to determine if such a tactic is within the terms of use. For example, Twitter allows cacheing the tweet, but not specific properties of that tweet item out of its context. Alternatively, a paid service might be utilized where the cost is based on the number of API calls.Cacheing would not be in their best interest from a business perspective. When cacheing data, respect the data privacy of the user and only use the data in the context of the applications intended use. This means, not sharing this cached data elsewhere.

API Keys

Many APIs require an API key. This key is used in requests to help identify who is making the calls. For basic functionality, most mapping APIs do not require authentication, they are open so they only care about the requestor’s identity, and can use it to determine the number of requests made along with other types of info. Many APIs require both an api key along with authentication to retrieve certain types of data.

Authorization

Many popular APIs have moved towards OAuth 2.0 these days. This video does a great job of explaining the process for OAuth2.0.

Authentication is required against the user to ensure the application/web site only has access to data that is user specific. Userless data provided by an API often doesn’t require this type of authentication – such as doing a Twitter search or a Foursquare popular venue search.

Re-inventing the Wheel

When working with an API, remember that someone has probably tried to do it before you. Many of the APIs out there have libraries available that can be utilized to get up and running much quicker. Ruby, C#, Python, PHP, Objective-C: search around for a library that might do some of the heavy lifting to let you focus on handling the data , and not wrangling it.

API Testing and Debugging

Many tools exist for debugging and testing http requests – and often test consoles are available from the API providers. Some tools that may be useful:

Wireshark
Runscope
Fiddler
Charles
Firebug ( Mozilla )
Firebug( IE 9+ )
Poster ( Mozilla )
Chrome REST Console extension
Hurl it
API Kitchen
Rest Client -Java application to test RESTful webservices
HTTP4e – Rest HTTP client for Eclipse
Online Console from Apigee
Pony Debugger for Native iOS apps