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