APIs and Standards

Recently I have been doing a lot of work with APIs. I have so far being tied into youtube, flickr, wordnik, isohunt and a few other rather big ones. I love putting together code and having it just work. I also love working with external services and having proper and clean documentation laid out in front of me.

The reason I am creating this post is primarily because of the lack of standards I have seen when it comes to documentation. So far the best documentation has been from Youtube and Wordnik and the worst was from Isohunt. It was really just a form post with an example call.

Flicker had some issues for me when it came to documentation because in my eyes a web service should have four main requirements listed on each of the calls page.

  • URL and method required to connect
  • Example request
  • Example response
  • Parameters with flags for optional or required

All of these things are rather simple and are the core requirements when it comes to creating a rest service call. All of the following should be displayed. It also helps to show response types as xml, json or jsonp when displaying examples.

I have run across two rather annoying things when working with these various APIs. First is that Yahoo needs to show that you can request json by adding a parameter to the query on the API’s method page. The second issue that I came across was the the YouTube object variable names.

The YouTube Api, in their most recent version, has used dollar signs in the variable name… This is a huge pain when working in php because it breaks the variable and causes a runtime error. The solution to get around this is rather simple but still, it should not be required to call an object property in a rather ‘hacky’ manner.

$result->{‘media$item’}->{‘$t’}

The only other complaint that I have, which you should correct in the next version of your API, is that variables need to be consistently named. This was an annoyance when working with the Isohunt API. All of the variables started with a lower-case first character except for one. I don’t care if your variables have been concatenated with an underscore or use camel case, just make them consistent please.

die(“EOR: End of rant.”);

Particles: Isometrics

Currently the only real work that has been going on is updates to the crawler and getting all of the resources figured out. I have set aside a little bit of time to work on particles. Particles is a javascript engine that can easily be added into a phonegap build.

I have gone on in previous posts about the projects and the intentions I have with it. If you would like to read more about it then I suggest that you go here: Shameless project plug

I have started working on an isometric view that will allow scaling and in the future panning. All of this requires me to build an overhead grid that the isometric view and renderer will plug into.

If you are interested in the project then I suggest you fork a copy or get in contact with me. All of the information can be found on the repository wiki pages.