Saturday, April 25, 2009

What is an API?

A game designer asked me the other day to explain the meaning of "API" - and I thought, wow, that is a good question, considering our massive (over?)use of the term on the web. Of course, the obvious meaning is "Application Programming Interface", but that's pretty damn non-helpful, particularly for a non-programmer. So here's what I told him:

There's the traditional meaning of "API" -

Some programmer writes a library with lots of functionality in it, and exposes the functionality as different functions, so that other programmers can just call the functions.

For instance, I could write a function that goes through all the complex steps of making out:

function makeOut(passionLevel, partsOfBody) {
 for (each partOfBody in partsOfBody) {

So if you want to have your code make out, then you could just call:

makeOut(10, ["neck", "ear", "mouth"]);

You don't have to worry about the "implementation details" - all that code I wrote - you just know that it works.

The "library" is the actual code, the "API" is what programmers need to know in order to use it.

So my API documentation would provide the minimal info needed to use the library, and it could look like this:

makeOut(passionLevel: Number, partsOfBody:Array)

For an example of actual API docs, Java has the online documentation for all of its common libraries here:

And then there are "Web APIs" -

A Web API hosts all of its code on one server, and documents how other servers can call that code.

There are JavaScript Web APIs, like the Google Maps API, where the Javascript is publicly viewable but quite "obfuscated" (compressed, hard to read).

This is our actual code:

This is our API documentation:

Developers only need to know what the API looks like, they don't have to figure out what all that crazy code means.

Then there are HTTP APIs, which means that all of the code is hidden on the server, and the code is executed when a programmer hits a particular URL. Often times, these APIs will create new information on the server for a user. All of our consumer products with user data have HTTP APIs - like Google Spreadsheets, Google Calendar, Blogger, etc. A programmer can hit a particular URL with an authentication header, and either get or create more user data.

One of the most popular HTTP APIs is the Flickr API, which can be used to retrieve information, upload photos, create albums, etc. Their API is documented here:

You can use the API without authenticating if you just want to do a simple search:

Notice the query parameters after the "?" like method, api_key, and tags. These are like the parameters to a function (like passionLevel and partsOfBody from above). You could imagine that flickr has code on their server that looks like:

function searchPhotos(api_key, tags) {

But once again, a developer never has to see the Flickr server code, they can just use the API and get the results they want.

Above all, an API is a promise.

It's a promise that no matter how the author changes the code (the implementation), the interface will remain the same. You can always call that makeOut function, and expect it to make out, even if it stops complaining about people watching.

Monday, April 20, 2009

Web09: Design, Code, Community.. and Maps!

Earlier in the year, I was invited to speak at Webstock, an annual conference in Wellington, New Zealand. It was a fantastic conference filled with inspirational speakers from around the world who discussed the future of the web, ways in which it sucks now, what we could do to change it.

This week, I had the opportunity to speak at Web09, a similarly named conference in Auckland, New Zealand - just an hour flight north. I was a bit surprised that New Zealanders felt the need to hold 2 web conferences in a year, and wondered if this conference would be different from Webstock. Well, it was completely different - in a good way. Web09 was a cornocupia of real-world advice from both local developers - like Karl Von Randow's talk about gaming the iPhone App store, and global evangelists - like Ryan Stewart's talk about new Flex features. Some of my favorite talks were:

  • Dan Rubin gave us a variety of ideas for creating better designs, including adding noise to a background, using your own photographs as the focal piece of a website, and scanning in every day objects to get web textures. In trying to define good design, he referenced Don Norman as the cognitive scientist who originally articulated the problem of doors that are so un-intuitively designed that they require signs - a problem that we have in our new Google building. Norman authored The Design of Everyday Things, which I've now put on my reading list.
  • Paul Burnett, Adobe Flash Evangelist, showed off various new features in Flash CS4 and its much better integration with AIR (now better than Flex Builder!). I was most impressed by the fact that Flash now supports adding bones (inverse kinematics) to shapes and graphics, and being able to set weights and properties and tweak the RTS graphs for every animation. It takes me way back (2 years!) to futzing around with character animation in Maya and Max, and makes me want to get CS4 and try animating a few simple characters - zombie, whale, maybe even a streetwalker.
  • David Karp, creator of Tumblr, described 5 areas of community building: engagement, use, negativity, change, feedback. Karp suggested that the reason that people participate in communities is for the "promise" of something happening - like the people who upload to Youtube thinking they have a small hope that one day their video will shoot to fame and they'll be a Youtube rockstar. Karp also described how Tumblr went from 1 support email a day to hundreds, and how they dealt with it. They categorized every support email as both "type of user" plus the actual problem - with user type ranging from paying customers and new customers to evangelist users. Visualizing the requests that way enabled them to decide what features were important to growth.

I myself gave a talk called "Avoiding Red Dot Fever: Tips for Improving Usability of Maps Mashups". It was a series of tips for ways web developers could improve the maps on their sites, based on my experiences seeing many badly-designed maps over the past 2 years. The talk went over really well (so well I was asked to give it twice), and gave me an excuse to meet the web developers of many New Zealand mapping sites - Zoodle, Yellow Pages NZ, vodafoneNZ, EventFinder, etc. The slides are embedded below, and there should be a video up in a few weeks.

Overall, it was a great conference, and I hope to see both Webstock and Web09 happen next year.

Thursday, April 9, 2009

Google Image Search + Color Restrict: Just look what you can find!

This week, Google officially announced support for filtering by colors in Google Image search results.I don't actually know if this is actually a useful tool yet, but even if it's not - it's freaking fun. Here are some cool results from myself and the twitterverse.

You can find beautiful landscapes: sky, red

You can find your school logos: usc, red
(via @oGLOWo)

You can find a world covered in fail stickers: fail, red
(via @niick)

You can find a phrase that's lived up to its colors: state, blue
(via @ManoMarks)

And one more of those: journalism, yellow
(via @KevinMarks)

You can find two colors at once: red, black

And finally, you can find creatures you never thought existed: dolphins, pink
(via @niick)

Wednesday, April 1, 2009

API Design: Beautiful Interfaces

This is part of a series on Web API design. The intro post is here.

When some developers think about the Google Maps API, they may envision a sea of GMarkers, GPolygons, GScaleControls, GOverviewMapControls, and the like. But really, it boils down to 2 things: GOverlay and GControl.

These two classes are interfaces in the API, and every class that is a visual item on the map extends from one of those two. Conceptually, a GOverlay is something that moves when the map moves and is somehow related to latitude/longitude coordinates, and a GControl is something that always stays in the same place, regardless of map movement. The screenshot below points to various examples in a standard maps mashup:

To add one of these to the map, a developer just calls addOverlay or addControl:

map.addControl(new GScaleControl());
map.addOverlay(new GMarker(new LatLng(37, -122));

To remove them, they call removeOverlay or removeControl.

There are some mapping APIs out there with calls like addMarker, addPolyline. This is is a bad idea for several reasons. It means you need an additional method each time you add a new visual class (bloating your API), and it likely also makes it hard for developers to extend the API. With generic methods like addOverlay or addControl, you can add a custom extension the *same way* you add a native class - so newbie developers don't have to learn a new syntax to add one to their map.

Along with using generic methods for adding stuff to the map, we can also take advantage of the interface to make our events more generic. A developer can listen to "addoverlay" or "removeoverlay" to find out when any overlay has been added to the map, and when they listen to a "click" event on the map, their callback gets passed in whatever GOverlay was clicked on. This means that whenever we add a new type of overlay to our API, the developer can continue using the same events they were before. We do often add specific events for each overlay later, but it's nice that the generic ones come for free.

And something for the advanced developers...

These interfaces make our API infinitely extensible in a standard way, and they're the reason I used the API for my personal and research projects even before working for Google. If I have a fundamental aesthetic issue with our GLargeMapControl3D, then I can simply create my own control (ExtLargeMapControl). If I want to visualize 5,000 markers, and GMarker is simply too full-featured and heavyweight for the job, then I can create my own lightweight marker (MarkerLight). If I want to visualize my points as <div>-based bar graphs instead of <img>-based markers, then I can create my own overlay (Bar).

To extend the interfaces requires defining only a few minimal methods:

GOverlay: initialize, redraw, remove

The initialize method, called when addOverlay is invoked, should create DOM objects for the overlay and append them to the desired map pane (there are several). The redraw method is called whenever the map moves, and it should re-position the overlay depending on the new latitude/longitude -> pixel mapping. The remove method, called when removeOverlay is invoked, should clean up any DOM objects created by the overlay. More info and an example is in the docs.

GControl: initialize, getDefaultPosition

The initialize method, called when addControl is invoked, should create and return the div for the control. The getDefaultPosition method should returns the recommended position for the control. There is no remove method, since the initialize method returned a <div> that the map can remove whenever removeControl is invoked. More info and an example is in the docs.

Using just these methods and some JavaScript/CSS skills, a developer can create anything their hacker heart desires. Custom controls and overlays account for 15/20 of the libraries in our official utility library, another 15 of the libraries listed in Mike William's list of 3rd party extensions, and based on my experience, many more are likely floating around in developer's code on the web.

Don't forget the actual API engineers...

Along the same lines, these interfaces also make API development easier for internal developers. If they want to add a visual class to the API, they just need to figure out whether it's a control or an overlay, define the methods, document that the new class exists, and external developers will use their existing familiarity with addControl or addOverlay to add it to their map.

It can't all be fluffy rainbows and unicorns...

We've certainly made a few mistakes along the way with the interfaces - but this post is getting long, so I'll save those for later.

To sum it all up...

The interfaces are easy for newbie developers to understand, easy for advanced developers to extend, and easy for internal engineers to implement. Beautiful.