This Is Not The Domain Name I Wanted

We’re going to take a quick look at a few obscure web APIs and see if we can’t learn a thing or two about what to and not to do when designing web APIs.

My focus will be the REST (Representational state transfer) style of designing web APIs, though not all the APIs I’ll look at claim to be RESTful. I’m not going to give an introduction to REST here because there are already very good ones out there.

1. MyAnimeList

MyAnimeList is a website for tracking the anime you’ve watched and the manga you’ve read. From the website you can add new ones, update them, etc.. And that’s all supported via the API. So, this one’s not too bad at all. Though it’s not quite RESTful in it’s url structure.

For example, the supported urls and corresponding HTTP methods for your anime list are:

http://myanimelist.net/api/animelist/add/id.xml (POST)
http://myanimelist.net/api/animelist/update/id.xml (POST)
http://myanimelist.net/api/animelist/delete/id.xml (POST, DELETE)

With REST, you don’t want separate urls for each function. The url specifies the resource and the HTTP Method says what to do.

Rather, to add an anime it should be

 http://myanimelist.net/api/animelist (POST)

to update it

 http://myanimelist.net/api/animelist/id (PUT)

and to delete it

 http://myanimelist.net/api/animelist/id (DELETE)

And while you can add, update and delete, there’s one glaring function missing – retrieving items from your list. You can query the entire database with

http://myanimelist.net/api/anime/search.xml?q=full+metal

but that wont give a user’s personal information regarding the results, such as number of episodes watched.

The only way I’ve found of getting a user’s list is undocumented, and not under /api/. It is:

http://myanimelist.net/malappinfo.php?u=docmarionum1&type=anime

That will some user info and their entire anime list (in this case my own). And this will get you the specific user’s information about the series, as well as the global data. This will pull their entire list and here is an example of one entry:

So, not perfect, but it at least resembles a RESTful API.

Lesson Learned: RESTful URLs should be nouns which represent resources (i.e. animelist, pickle, cow) and the HTTP method used to access it defines the action. POST creates something new, PUT updates existing resources, GET just returns the information associated with a resource and DELETE…deletes.

2. Steam

For those who don’t know, Steam is a digital games distribution software.  They offer an API for getting information about players.

A sample call looks like:

http://api.steampowered.com/ISteamUser/GetPlayerSummaries/v0002/?key=XXXXXXXXXXX&steamids=76561197961911445

where key is your personal API key and steamids is a comma separated list of player ids.  In this case, I queried my own account, and the response is:

The default format is JSON, but by passing a format parameter the format can also be changed to XML or a proprietary format called VDF (Valve Data Format).

The Steam API is not a great example of a web API.  There are only 4 functions and they are not consistent.  They also have long URLs, and all have three sub-urls, even though two could be uniquely identified by the first.

Then there’s the matter of the version number (v0002).  Having a versioned API sounds like it could be a good idea so changes wont break old clients if you need to change formats or add new attributes, but that then requires your code to completely support all the old versions.  One recommendation is to not include the version number in the URL, but also provide an alias to it with the version number, such as

http://api.steampowered.com/ISteamUser/GetPlayerSummaries/

http://api.steampowered.com/ISteamUser/GetPlayerSummaries/v0002/

both pointing to the same place while

http://api.steampowered.com/ISteamUser/GetPlayerSummaries/v0001/

will return a redirect code, indicating that the API has changed.

Lesson Learned: Only use version numbers to indicate to clients when they are using an obsolete version. Don’t make it a required part of the URL.

3. MTA

“Whiz kid certified” my ass.  I wouldn’t even call this an API, more like a collection of somewhat-frequently updated information.  Most of it is in zip format.  Try using that in your dynamic application.  Though there are two usable datasets.  One is for the status of escalators and elevators throughout the system and the other has the status of subways, buses and trains.  That’s really the most important one, so at least that’s available.  Let’s take a look.

Hitting http://www.mta.info/status/serviceStatus.txt  will give you an xml file with the time updated, and the status of all the lines.

A subway line block looks like:

Looks servicable. And even more surprisingly, only one train line had any delays.

Fuck – that’s my line. Also notice that they’ve encoded html tags into the text field. That gibberish translates to <P> and </P>. Why would they put formatting information into there? The application using this should be responsible for doing any formatting necessary.

The offense is even more obvious when we take a look at one of the delayed bus lines.

What in the unholy fuck is that? This clearly contains styling information specific for the MTA’s service status page. Why would you leave that in a data source that is supposed to be used by the public? Anyone else who wants to use this first has to get rid of that crap.

Well, I can’t really say that I’m surprised with the state of the MTA’s “APIs.”

Lesson Learned: A web API should only return data, not formatting or styling information.

4. Biblia

Biblia’s API allows for quite a number of operations – listing different bibles, searching bibles, comparing verses, etc. It’s not RESTful, but it is full-featured.

I’m just going to use the standard King James Bible. We can first get some information about it with the find function

http://api.biblia.com/v1/bible/find.xml?key=XXXXXXXXXXXXXXXXX&bible=kjv

Which returns

Then we can search the text of that bible with

http://api.biblia.com/v1/bible/search/kjv.js?query=ass&mode=verse&start=0&limit=3&key=XXXXXXXXXXX

The last part of the url specifies the bible to search, in this case kjv for the “Authorized Version” of the King James Bible. I’m querying for the first 3 instances of the word “ass.” The response is

The response tells us the number of different passages with the word and the total number of times it occurs, and then returns the specified number of passages. “saddled his ass”…hehehe.

I quite like the Biblia API. It’s extensive, offers a bunch of different format options (JSON, XML, txt, HTML, HTML wrapped in JSON), and is consistent.

Lesson Learned: If you want people to use your API, it should do lots of stuff and support as many formats as possible to make it easier to use.

+1. This Blog

Thanks to the JSON API plugin for WordPress, even this blog has an API. You can get posts by id, name, tag, etc.; create posts, and submit comments.

For example, to get this post:

http://thisisnotthedomainnameiwanted.com/api/get_post/?post_id=8

It returns

You can’t do everything through the API, but if you’re running a WordPress site, there’s no reason you shouldn’t have it.

Lesson Learned: You never know when someone might want to use your content. Make it as easy as possible to use.