Showdown: Google Contacts API versus People API

So we are all in on the People API. You can read about how we’re supporting our customer’s migration here.

---

We’re all looking for ways to grow and embrace the newest and freshest innovations in all areas of our life. For Developers, this means a lot of time to build out the new apps or adding new features to optimize for your customers. The best part is that you can definitely toss out Google Contacts API in favour of the newer Google People API.

CloudSponge has a long lifetime of integration with the Google Contacts API (going way back to Portable Contacts and OAuth1.0), so it’s vital that we stay abreast of all the changes and updates. We stay up to date on all of the most recent upgrades to stay on the cutting edge of functionality for our clients. There’s been a lot of discussion and speculation by developers as to what Google is planning to do next. What is their next big innovation in our arena? Is Google’s Contacts API on the way out, and if so…what’s taking its place?

In case you haven’t been keeping up with the news on the Google Contacts API, here is a quick refresher. Over the past couple of years, Google has posted that they intend to deprecate the Contacts API. This deprecation will necessitate a move toward its more modern relative, the Google People API. With that in mind, developers want to know when this change is going to take place, and what differences can be expected.

Contacts VS. People

In the Ring…the reigning champ “Contacts,” versus the challenger “People!” Well, it may not be that much of a prizefight at “Contacts” age, but instead a boosting of a newer and more developer-friendly API. The official name, “Google’s People API,” is meant to sound broad and fully encapsulating of a user’s contacts. It’s named as such because this broad-spectrum functionality is the main goal of the new API. Google’s People API is intended to make the comprehensive gathering of all the people with whom a user interacts a very intuitive, seamless, and simple process.

A transitional pattern very similar to this can be seen on Microsoft, which has an API called “People” as well. Perhaps not coincidentally, they also have two APIs just like Google…and their People API takes the innovative leap into bringing in identities from a vast array of locations that are relevant to the user.

This all sounds great…right? Initially, the People API didn’t work as advertised, which may still be scaring people off. However, now that People API has fixed its bugs, Contact API has been deprecated. This means that if you relied upon Contact API and wish to continue doing so, you’ll have to switch to People API.

Unfortunately, Google’s People has not yet been able to deliver on the promises that it’s making. Although there are dreams of grandeur, the functionality of the API just isn’t there yet. That’s probably why Google is keeping their Contacts API rolling and will hopefully continue to support it until People has been further developed.

Google is still suggesting that Contacts will be deprecated sometime in the near future, but they haven’t set a date on that so far. As such, we are not in any imminent danger of losing access to the Contacts API.

Just for peace of mind, Google is pretty good at giving everyone a “heads up” when any major change is coming down the pipeline.

So…what actually qualifies as a “Contact” in these APIs?

Some of you might be curious about what exactly constitutes a contact? In the universe we’ve been talking about, the details of parameters become important in relation to how the API works. So is a contact somebody that I’ve communicated with? Does that mean that they’ve emailed me or I’ve emailed them? Have we had at least one back and forth?

The criterion is quite simple. According to Google’s help, “Other contacts” is where (among a couple of edge-cases) Google automatically creates a contact when you send them a message. They do this to enable auto-complete on the email address for future email composition. So basically this means that the entity to which you send any email becomes a contact.

The umbrella under which entities are deemed a contact is quite expansive. It includes everyone you’ve emailed in at least the past seven years.

There’s been some discussion about the potential for malicious contact “adds.” This is basically the idea that someone could add themselves to your contact list just by emailing you. However, this is very unlikely. Without a user sending or replying to an email, it won’t be captured as a contact.

How are these APIs Meeting the User’s Expectations?

There is some good news about these two APIs. They are both flexible in that the configuration in Google Cloud Platform / Google Developer Console / Google APIs Console (or whatever they are currently calling it) doesn’t need to change between these APIs. In addition, when you have Google verify your app to use one of these APIs, it also applies to the other.

The purpose of the transition to Google’s People API is to ultimately optimize the user experience and to simplify the process of collecting and transferring Contacts between platforms. Contacts is the older of the two, and when it was first created it embraced XML. It’s been through a number of versions, but each version continues to have the XML payload. It will return data in a JSON format, but the names of fields makes it quite obvious that it’s just poorly translated from XML. It’s a bit awkward when you’re digesting that payload, even though it’s in a JSON format.

Your code is looking for strangely named entities to get the data you want. It’s just not as intuitive in terms of breaking down the payload.

In case you’re a nerd for the details like we are, here is a good concrete example:

XML nodes have zero or more attributes as well as a text value. The literal JSON translation of this nests every value inside a $t property. Also, the JSON includes some XML namespaces in the property names so we get oddly named properties.

E.g. one wonky-looking value is: {"openSearch$totalResults": {"$t": 10}}

The People API was released without being able to add all Google Contacts, but they’ve since resolved this issue. In other words, it’s definitely time to begin moving to People API, if you haven’t already.

We’ve Already Made the Switch to People API

Now that People API has been updated to align with the Gmail UX, it’s more than time to stop using Contacts API. Of course, you can safely ignore this material if you are a CloudSponge customer since we monitor the APIs for changes, and we’ll make the changes on our side.