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 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.
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.
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:
Firebug ( Mozilla )
Firebug( IE 9+ )
Poster ( Mozilla )
Chrome REST Console extension
Rest Client -Java application to test RESTful webservices
HTTP4e – Rest HTTP client for Eclipse
Online Console from Apigee
Pony Debugger for Native iOS apps