APIs: Who? What? Why? How?

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?

Who? :

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).

The most popular apis are released in such services as Google Code, Flickr, Del.icio.us, Facebook, and MySpace.

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.

Why? :

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.)

How? :

My 10 Step Program:

  1. 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.
  2. 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!)
  3. 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).

  4. 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.
  5. Output the data to the screen or a file for later storage. Html is usually quite nice.
  6. Run the page and find out you have a gazillion errors. Go back to #4 until you have them all fixed.
  7. Share with your friends to show how geeky you are.
  8. Clean up your code and provide lots of comments so you can understand what you did later.
  9. Find ways to make your script run faster.
  10. 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:

  1. 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.”
  2. 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.
  3. 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).
  4. 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.
  5. Mash-it-up! Working two apis together is really, really fun. Possibilities are (almost) endless.

5 (Actually, 6) Three Letter Acronyms for Librarians


What it stands for: Three-Letter-Acronym

What it should stand for: Lazy Coder’s Obfustication Device

How to recognize it: Three letters; used in place of actual words without explanation.

What it does: Makes computer geeks feel a little bit more sophisticated than they really are.

What a librarian needs to know about it: Don’t be afraid of it; Google it or Wikipedia it and use this glossary to see if you can make some sense out of it.

Similar to: Technical Jargon, Library Jargon, General B.S.

My mission in blogging life so far has been to make the very technical or confusing just a little bit more easy to understand for librarians who tend to teeter on the edge of coding expertise and wishing the whole technical aspect of web design would just go away.

One of the very things that appears to stand in the way of understandability in technology concepts is the TLA, described above. So, I decided to provide a brief glossary of 10 three-letter-acronyms to see if I can make it a little simpler.

Here goes:


What it stands for: eXtensible Markup Language

What it should stand for: Esperanto for Computer software.

How to recognize it: Diamond brackets and forward slashes.

What it does:

  • It describes data, including the data that may, in the end, describe data.
  • It acts as a standard so different computer languages can talk to each other.
  • It is a format for other standards, such as RSS and TEI
  • It can also be used as a text-based database, or in tandem with Database systems such as MySQL or PostGREgreSQL.
  • Various related standards is also used in templating (XSLT), web services (SOAP) and even Browsers (XUL).
  • And it is the source of many other TLAs if you hadn’t already noticed.

What a librarian needs to know about it: It’s a standard; it’s cataloguing (or at least source description); it’s widely used by coders of all types; it makes stuff more “open” and available to others.

It’s similar to: JSON, HTML, SGML, MARC


What it stands for: Application Programming Interface

What it should stand for: “Mi Casa, Su Casa” Software;

What it does:

  • Provides the language and instructions so coders can bring the features of an online service into their own website.
  • It lets people do Mashups with your service.
  • It frees your data.

What a librarian needs to know about it: Information wants to be free, so you should be asking for one of these any time you buy a product — especially if that product houses data that belongs to you. Oh yeah, and your programmer folks will need to learn a few of these if they want to apply something like Google Maps, Facebook Apps et. al to your services.

It’s similar to: XUL, Widget, Mashup


What it stands for: Cascading Style Sheets

What it should stand for: “Hey I Just Completely Changed My Website in the Blink of an Eye!” language

What it does:

  • Provides style and colour instructions for the html on your website.
  • You can say things like “Anything within a ‘paragraph’ tag in my html ought to be yellow and Arial font”
  • It saves you the pain and suffering of re-writing lots of html just to make a simple stylistic change.

What a librarian needs to know about it: Besides saving you time it can also save the load time on your website because it prevents you from having to use tables to style your pages. Although that theory is under dispute.

It’s similar to: XSLT-FO, Skinning, Templates


What it stands for: Personal Home Page, PHP: Hypertext Preprocessor

What it should stand for: “Hey Server, Starting Thinking for the User” Programming Languages

What it does:

  • Tells the server to do stuff, based on user-input, time-of-day, or any other parameters.
  • It displays the stuff in a database or xml file in nice, clean html.
  • It makes your websites a little bit more difficult to troubleshoot, burping when something happens unexpectedly.

What a librarian needs to know about it: A PHP (or other language)-driven website is automatically more complex than one that is straight-forward html. On the other hand, it is more dynamic and make wonderful things happen for your customers.
It’s similar to: ASP, JSP, Ruby


What it stands for: General Public License

What it should stand for: Take My Code, Please!

What it does:

  • Gives permission to coders to re-use and/or the code of software possessing the license, so long as their product uses the same license.
  • Drives open source software and ensures that affordable software continues to exist.

What a librarian needs to know about it: Like Creative Commons and a variety of other licenses, GPL is an opportunity for users and developers alike to create, explore and play with new technologies.

It’s similar to: Creative Commons, BSD

There it is! Anyone else have a TLA that gets overused in library land without explanation?