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.

As you might know lisp hosting is not abundant so must of the time you need your own server instance to run your lisp on. However instances are relatively expensive when compare to other hosting options so it might be useful if you could run multiple websites of the same server. And it turns out you can do exactly that with hunchentoot and you do not need multiple instances of your common lisp running (I use SBCL).

Your first option is to visit Cyrus Harmon website and get his hunchentoot vhost code and run it on top of your hunchentoot. The code is clean and understandable and last i checked Cyrus uploaded a new version on 12 June 2009.

Your second option is to use hunchentoot built in capabilities and separate your websites on different ports (you could use a webproxy in front but that is another post). Start by creating your hunchentoot instance in the following manner:

(hunchentoot:start (make-instance ‘hunchentoot:acceptor
:port port
:request-dispatcher dispatcher))

Now the important part is that we started by telling this particular instance that we need hunchentoot to listen to the designated port. The key thing you need to take care of however is the parameter request-dispatcher. It turns out creating a hunchentoot acceptor this way you can no longer use any of hunchentoot built in dispatcher functionality (Which is the price you have to pay). So how to deal with that is to make sure that the dispatcher is actually a function that return the appropriate html.

This function needs to take one argument which is the response object and then return the proper html based on the response. There are different ways to do this that could be fast. One suggestion which I implemented was to create a hash table with the url as the key and the handler function as the value and i simply do a funcall on the handler function. it is that simple .

Hope you enjoyed the above and stay tuned for some more information on lisp programming.