Trail of Light

Anyone who is following the Google world can see that the Google APIs are taking quite a chunk of the talk (maybe right after Android). The idea behind the API themselves are very good and the fact that you can do a great many mushups using the Google Platform is just very cool. Unfortunately, in my experience, that is where the slippery slope from coolness starts.

About a month ago I started working on a little product idea called SMSTheTeam which would leverage Google’s Contact, Document and Spreadsheet API all while running on Google’s AppEngine. The start was quick and easy with AppEngine’s SDK and the Google API Documentation. I was able to come up with a proof of concept in a couple of days and then things went haywire.

Now as a disclaimer I am not sure if this is an issue in just Google’s setup or in the python Google API library, but I suspect the former plays a large role since it seems that Google endorses the python library by using it in their examples. Let me start with a case point which is the simple authentication sequence. Now almost all the examples show the using of authentication for a single Google service when using a session token, but what about if you want to use two services. In one place the documentation states that they should be separated by a blank in another it states they should be a list. Trying both did not work even though the forum discussion supported the second.

The solution amazingly is that you do need to use a list but what is not mentioned is that after you upgrade your token you get a new token from Google and that is the token that you need to manage and keep. Now to be fair it is easy to deduce that is the logic behind the process but with a detailed documentation I should not be making assumptions should I? More importantly the documentation does not mention that you need to use the variable auto_set_current_token and set it to True for you to be able to use the token later on.

And the worst part some things are just not documented in some versions. Like for example the insertRow function in the Spreadsheets does not appear in v1.0 even though the python library does support it and the fact that the list given to the function should be all small letters is barely mentioned (which causes some frustration let me tell you)

I do not know if others have found the same disappointments in Google’s API documentation but it is a shame to see that the guys behind the API are doing so much work (they are in version 3) when so many things are left undocumented or requiring too much work to turn into proper robust code. I wonder how many mushup opportunities were lost to that. So in conclusion Google’s API…great, but their documentation…merely good.