APIs (Application Program Interfaces) are among those things that most presenters talk about with the caveat: “You do not have to know how to do it; you only need to know they exist.” You have to be fair to the presenters — an api is not really something you can explain without actually demonstrating how to use it.
Well, since I spouted a challenge to all those Learning 2.0-ers out there, that they can and should learn a little bit about what goes on under the hood of Web 2.0, I thought I’d give explaining apis a shot. I’m going to do this using four questions: Who? What? Why? How?
APIs are most often released by web-based companies that host data created by users. Offering an api in this context is rather obvious: if users create the data, they might want to use it in other places around the web. Business-to-business web services may also offer apis to partners so business can happen more quickly and efficiently (think VISA, PayPal & eBay).
Two apis that I’m going to describe today (with limited detail) are the Twitter, & Twitter Search apis. If you are a beginner, I think the Library Thing api is also quite nice and simple to play with.
This is where you are free to doze. Just a few acronyms to get you through your day.
- REST (Representational State Transfer) : This basically means “getting XML data from an api using Http and a URL.” It is the most popular because it is easy.
- GET/POST : Http commands to do stuff with an api. A “GET” usually means you are just going to output data to the screen. A “POST” usually means you are going to store the data somewhere (eg. in a database).
- cURL : A popular way to get api data without being worried that the data will cause bad things to happen to your server. Using cUrl is often mandatory with web-hosted servers (like Dreamhost).
- XML/JSON : Two different ways to markup data. JSON is faster and more friendly when using AJAX. XML is slower, but easier to read, and more easily handled by server-side scripts like PHP.
- SOAP (Simple Object Access Protocol) : A harder and more particular way of using data in an API. I’m not going to talk about it much, but suffice it to say that it uses an XML-based protocol to make api requests.
- WSDL (Web Services Description Language : A complicated standard a Web Company can use to make SOAP a bit easier to use for the rest of us. It meticulously describes every command someone can use in the api.
In general, simple services offer simpler (REST) apis. Get into large, complicated services where money gets exchanged or whatnot (eg. Business to Business data exchange, eBay) and you are going to find SOAP and WSDL.
You would use a API for the following reasons:
- to create a widget for your website or blog.
- to create a Mashup (a combining of two different services).
- because you want to store or organize data in a service for your own personal use.
- to do something cool without having to build a service from scratch.
- to provide a unique way to show a service’s data (eg. tag clouds, visualizations etc.)
My 10 Step Program:
- Read the api instructions and find out what you can and cannot do with the api. For instance, the Twitter api does not (as of today) offer a “search” for twitter. For that you need the Twitter Search api, which is an entirely different web service. UPDATE: Twitter now offers its own Twitter Search api.
- Choose your coding method. Yup! APIs require coding ability — that’s why conference presenters don’t want to spend too much time explaining it to you. AJAX is the client side api tool. PHP, JAVA, PYTHON & RUBY are probably the most common server side tools. (Don’t stop here just because you do not know how to code. I can at least explain the process of how apis work!)
- Use Curl (PHP etc.) or the HttpRequestObject (AJAX) to grab information from a URL. What you want to do is usually indicated through the URL. For instance, to get the last 20 statuses from one of your friends (MYFRIEND) in Twitter you would use
(using your username and password from Twitter).
- Use your coding skills to manipulate the data you receive from the URL. PHP has a nice tool called SimpleXML to do this. AJAX uses the XML DOM. XPath is another way to get your way around an XML file. Or maybe you just want to template the data using XSLT.
- Output the data to the screen or a file for later storage. Html is usually quite nice.
- Run the page and find out you have a gazillion errors. Go back to #4 until you have them all fixed.
- Share with your friends to show how geeky you are.
- Clean up your code and provide lots of comments so you can understand what you did later.
- Find ways to make your script run faster.
- Secure the code (hiding that username and password might be a start).
That’s the basics behind using an api.
Final Words :
API is a buzz word in many circles. I have seen it bandied around by all sorts of people who have no true understand about what it is or what it does. Knowing what an api is will help you make better decisions about products. Here are some api axioms for librarians:
- Demand an api. Web-based products that store data you own should have an api of some sort. Look to the competition or an open source product if your product people say “no.”
- You need to know what you (or your coders) can do with that api. It ought not be enough for a vendor to say your desired product has an api. Creating an api is easy. Creating a useful api is more challenging.
- Respect the rules of the api. Each time you call that URL for the api means you are using the service’s web resources. Most services create limits on the number of request you make per second (usually no more than one per).
- Expect alot, but not the moon. Apis cannot do everything. Expecting to be able to search gazillions of items from an http request in an XML file is not going to do you or the service favors (especially if that search includes an “OR,” a “NOT” or any regular expression. Expect to get a limited amount of data in a single request. If you want more, store it on your own server (with permission or license) and work it that way.
- Mash-it-up! Working two apis together is really, really fun. Possibilities are (almost) endless.