Google Apps Provisioning API Version 2

Google Apps Provisioning API is a set of API that allows other programs to access stored on Google’s servers. This is done via the Atom Publishing Protocol and HTTP requests (what the industry terms general as a RESTful interface).

The set of data that Google exposes via the Provisioning API include the user accounts and groups and other related data.

Google has improved its groups mechanism not too long ago. With this came improvements to other Google properties such as Google Docs where sharing documents with groups is possible. Previously, this was not available because the original concept of a group in Google Apps is nothing more than an email list where emailing to the “group” allowed users in the “group” to receive the email as well. But this was all that version 1 of “groups” (technically known as an email list) could do.

Version 1 of the API also had a limited capability – it allowed developers like us only to create email lists with a name that is the same as its ID. The API for manipulating membership is there but there was no way to change the group name (title) nor the type of group. You see, in Google Apps, a group (that is a mailing list) can either be a Team, an Announcement, or Public. Version 1 of the API does not allow us to change that – all groups created through the API were Public. Furthermore, there wasn’t the ability to specify a member as the owner or plain member of the group.

Well, all that changed with version 2. All the operations described in the above paragraph are now available with version 2. The issue now is that I’m using PHP to develop my e-learning application. To access Google Apps’ API, I’m using Zend Framework’s Gdata library. The library, however, only has PHP implementation for version 1 of the API.

So to get version 2 working, I used the base classes in Zend and built a new class for working with groups, which had the most changes. I created the functions to be as similar to the old functions as possible. There is this one function that is supposed to accept a parameter to indicate which group to begin retrieving from – this acts like a sort of paginator. In version 1 of the API, this parameter is named “startEmailList” and it accepts a value that is the email address (or the ID) of the group less the domain name e.g. group1 (without @domain.com).

So I searched high and low in the documentation for this parameter – no mention of it anywhere. Posted on the mailing group – no reply after a day. Then I noticed in this link at the bottom of the page that there is no corresponding method in groups as that in email lists (retrievePageOfEmailLists).

“Could there be a mistake in the documentation? Or the Provisioning team never meant for the same function in groups?” I thought to myself.

After getting no reply in my post, I decided to experiment it myself. So I created 220 groups in my domain and retrieved the first list of groups. Since each list contains up to 200 entries, I could inspect the “next” link in the feed to see what the parameter was. This is what I got:

https://apps-apis.google.com/a/feeds/group/2.0/gsatech.com.sg? start=AHmOf6Y99TubWlxcd-1p2TT7zmo81nEL4K9aEiNzddfCD6CeUtJmT4Is8Dru- G7TnxU60X9ZwI75mFcQBqQmGt5nIbYp5SEZdpoX3gVrVpxb6g-9DS3jTPv5SsxoS6uR6GChqp_WRhH_ ID8wt5xdfoMATPhVGFbxZaormIFAoYmPfJ_KveGFF6I

All one line. So it’s apparent that the keyword for the next page is “start”. However, the value is not. Like I mentioned above, in version 1, the parameter expected a value that is the ID of the group. This however, is a hash of something.

Coupled with the documentation, I came to the conclusion that the Provisioning API team did not want us to manually page the results.

Google Provisioning Team: you could have saved us some work by putting this information somewhere in the documentation.