Editor’s note: This is a guest post by Martin Böhringer, Co-Founder and CEO of Hojoki. -- Steve Bazyl
Hojoki integrate productivity cloud apps into one newsfeed and enables sharing and discussions on top of the feed. We’ve integrated 17 apps now and counting, so it’s safe to say that we’re API addicts. Now it's Time to share with you what we learned about the Google Apps APIs!
Our initial reason for building Hojoki was because of the fragmentation we experience in all of our cloud apps. And all those emails. Still, there was this feeling of “I don’t know what’s going on” in our distributed teamwork. So we decided to build something like a Google+ where streams get automatically filled by activities in the apps you use.
This leads to a comprehensive stream of everything that’s going on in your team combined with comments and microblogging. You can organize your stream into workspaces, which are basically places for discussions and collaboration with your team.
To build this, we first need some kind of information on recent events. As we wanted to be able to aggregate similar activities and to provide a search, as well as splitting up the stream in workspaces, we also had to be able to sort events as unique objects like files, calendar entries and contacts.
Further, it’s crucial to not only know what has changed, but who did it. So providing unique identities is important for building federated feeds.
Google’s APIs share some basic architecture and structure, described in their Google Data Protocol. Based on that, application-specific APIs provide access to the application’s data. What we use is the following:
The basic call for Google Contacts for example looks like this:
https://www.google.com/m8/feeds/contacts/default/full
This responds with a complete list of your contacts. Once we have this list all we have to do is to ask for the delta to our existing knowledge. For such use cases, Google’s APIs support query parameters as well as sorting parameters. So we can set “orderby” to “lastmodified” as well as “updated-min” to the timestamp of our last call. This way we are able to keep the traffic low and get quick results by only asking for things we might have missed.
If you want to develop using those APIs you should definitely have a look at the SDKs for them. We used the Google Docs SDK for an early prototype and loved it. Today, Hojoki uses its own generic connection handler for all our integrated systems so we don’t leverage the SDKs anymore.
If you’re into API development, you’ve probably already realized that our information needs don’t fit into many of the APIs out there. Most of the APIs are object centric. They can tell you what objects are included in a certain folder, but they can’t tell you which object in this folder has been changed recently. They just aren’t built with newsfeeds in mind.
Google Apps APIs support most of our information needs. Complete support of OAuth and very responsive APIs definitely make our lives easier.
However, the APIs are not built with Hojoki-like newsfeeds in mind. For example, ETags may change even if nothing happened to an object because of asynchronous processing on Google’s side (see Google’s comment on this). For us this means that, once we detect an altered ETag, in some cases we still have to check based on our existing data if there really have been relevant activities. Furthermore, we often have trouble with missing actors in our activities. For example, up to now we know when somebody changed a calendar event, but there is no way to find out who this was.
Another issue is the classification of updates. Google’s APIs tell us that something changed with an object. But to build a nice newsfeed you also want to know what exactly has been changed. So you’re looking for a verb like created, updated, shared, commented, moved or deleted. While Hojoki calls itself an aggregator for activities, technically we’re primarily an activity detector.
You can think of Hojoki as a multi-layer platform. First of all, we try to get a complete overview on your meta-data of the connected app. In Google Docs, this means files and collections, and we retrieve URI and name as well as some additional information (not the content itself). This information fills a graph-based data storage (we use RDF, read more about it here).
At the moment, we subscribe to events in the integrated apps. If detected, they create a changeset for the existing data graph. This changeset is an activity for our newsfeed and related to the object representation. This allows us to provide a very flexible aggregation and filtering on the client side. See the following screenshot. You can filter the stream for a certain collection (“Analytics”) or only for the file history or for the Hojoki workspace where this file is added (“Hojoki Marketing”).
What’s really important in terms of such heavy API processing is to use asynchronous calls. We use the great Open Source project async-http-client for this task.
When I wrote that “we subscribe to events” this is a very nice euphemism for “we’re polling every 30s to see if something changed”. This is not really optimal and we’d love to change it. If Google Apps APIs would support a feed of user events modelled in a common standard like ActivityStrea.ms, combined with reliable ETags and maybe even a push API (e.g. Webhooks) this would also make life easier for lots of developers syncing their local files with Google and help to reduce traffic on both sides.
gContact:status
<gcontact:status indexed="true"/>
indexed
false
A while back we began a series of articles about integrating with Google Apps and the Google Apps Marketplace, starting with how to make a great first impression on your users. Today we're continuing that series with an eye on collaboration and the various "people" APIs in Google Apps -- Contacts, Shared Contacts, Profiles, and Provisioning.
Why contacts? Contacts data is used pervasively and makes it easier to share documents, arrange meetings, or communicate in general. It's synced with mobile phones & email clients. Many apps in the Google Apps Marketplace use contacts to help users share projects and assign tasks to coworkers. In short, the contacts APIs act as a hub for applications and devices to share important information about the people users communicate and collaborate with the most!
Before jumping in to how to use these APIs to make work easier for users, let's take a step back and look at the role of each API.
Contacts API - This API provides access to an individual user's personal contacts & is available to all users on all editions of Google Apps. Each user manages their own contacts separately.
Shared Contacts API - The shared contacts API is available only to Google Apps for Business and Education editions, and provides a way for domain administrators to manage a global address list of external (non-employee) contacts viewable by all users in the domain.
Profiles API - Like the Shared Contacts API, the profiles API is only available for Google Apps for Business and Education education, and is managed by domain administrators. But while shared contacts can be used to manage contact information for people outside the domain, the Profiles API is exclusively for managing contact information for users in the domain.
Provisioning API - A distant cousin of the others, the Provisioning API allows domain administrators to manage users, groups, and organizational units in their domain. While the full version of the API is restricted to Google Apps for Business & Education editions, all editions support a read-only view of the data and it can be a quick and easy way to discover organizational information for a domain.
As mentioned in our earlier post on creating a good initial experience, these APIs, can be a great way to help administrators set up and configure applications quickly. The provisioning API in particular is well suited to this and provides user, group, and organizational data for a domain.
Expensify uses the provisioning API to quickly configure roles and reporting relationships for submitting expense reports.
There are a variety of ways to use the various contacts APIs to help users save time and be more productive. Project & task management apps often benefit from importing contact information to speed user entry.
Manymoon's project management app helps users assign tasks quicker by auto-completing names as the user types.
Likewise, CRM and marketing automation apps can also speed user adoption and reduce the need for time consuming data entry by importing existing customer data stored in contacts.
Importing contacts to Bantam Live
For applications that aim to be the system of record for contact or employee information, pushing data to Google Apps can be a big win both for users and developers. Syncing contact data with Google Apps means syncing with every other application and device that syncs as well. It allows developers to magnify the reach of their integrations and lets users access important partner data no matter what the context.
Sharing contacts with BatchBook
Full bi-directional contacts synchronization is more challenging. It can be equally rewarding. Not only does it allow users to edit contacts in context, it can enable innovative new services that seamless enhance data without disrupting how users work.
Rainmaker's bi-directional sync automatically enhances contacts with data from social networks and other sources.
While the example so far have focused on the Contacts API and individual users, synchronization with the Shared Contacts API can provide added value for larger organizations on Google Apps for Business.
As our friends over at Manymoon wrote not too long ago, they learned three key lessons about what it takes to be successful in the Google Apps Marketplace: Appeal to a broad audience, integrate deeply, and demonstrate immediate value. Integration with contacts & provisioning APIs is a great way to do accomplish those goals that just about any app can benefit from!
Posted by Steven Bazyl, Google Apps Marketplace Team
Want to weigh in on this topic? Discuss on Buzz
![](https://blogger.googleusercontent.com/img/b/R29vZ2xl/AVvXsEgHB-WOcCzSSybfco0vxl1sAz3rmLIMsD4cXkm6NdR5oeV9ETdmTVcvtGGtJ_q6TDLd_Dl3Lkf74qzAq0qtbpuJRjtUKK2_CSOB4u1C-KX6WXzh75tF8gaEjqVr72BRrr4prfHm31MPO2o/s400/martin.png")
