I See... People

To get a better understanding of the new Google People API I created a small (of course Polymer-based) demo, since playing around with the API Explorer can be cumbersome.

https://scarygami.github.io/people-api-demo/

This demo will fetch one "page" of results from the people.connections.list method and display the raw JSON for each contact.

You can then click on "load full data" to fetch the rest of the contact information via people.get for each contact.

Source code for the demo is available if you want to play around some more.

https://github.com/Scarygami/people-api-demo

The demo makes use of my discovery-api-elements element, that I should really get around to write a more detailed article about, since, if I may say so myself, this is an awesome way to easily access all of Google's discovery-based APIs and your own Google Cloud Endpoints.

---

Some takeaways from what I've seen so far in no particular order.

The "resourceNames" are interesting

If you want to fetch the data for a Google(+) account, instead of just using the numeric ID, you will have to use people/ID
This is easy enough to get used to, but makes you wonder what other resources they might have planned to include in this API.

The data structure is confusing to look at

To be fair JSON isn't really meant for human consumption, but to be able to work with it programmatically you first have to understand it.

Each person has one or more sources where the data comes from.
In most cases there will be two:

• CONTACT from your Gmail contact information
• PROFILE from the public Google(+) profile.

{
  ...,
  "metadata": {
    "sources": [
      {
        "type": "CONTACT",
        "id": "gmail_id"
      },
      {
        "type": "PROFILE",
        "id": "gplus_id"
      }
    ],
    "objectType": "PERSON"
  },...
}

For each "type" of data (e.g. names, photos, urls, emails, phone numbers, ...) the response will have an array, and each item in this array comes with metadata to show which source the information comes from. While this makes perfect sense for easily parsing and displaying the information programmatically it results in a rather lengthy JSON response. This block here is only for two email addresses:

{
  ...,
  "emailAddresses": [
    {
      "metadata": {
        "primary": true,
        "source": {
          "type": "CONTACT",
          "id": "gmail_id"
        }
      },
      "value": "email1@gmail.com",
      "type": "other",
      "formattedType": "Other"
    },
    {
      "metadata": {
        "source": {
          "type": "CONTACT",
          "id": "gmail_id"
        }
      },
      "value": "email2@somewhere.com",
      "type": "other",
      "formattedType": "Other"
    }
  ],...
}

Google+ profile images are broken

A bug that will hopefully be fixed soon, but for now the profile photo URLs  that come from PROFILE give a 404. Interestingly profile photo URLs from CONTACT work, as do cover photo URLs.

No access to "private" profile data even if you are allowed to see it

That was one of the biggest problems with/complaints about the Google+ API's people.get method as well. Even if you are using authenticated calls you only get the public Google+ profile information which doesn't include the private/limited data you might see when visiting someone's Google+ profile. Unfortunately that hasn't changed with this API...

No Google+ contacts

The people.connections.list method only shows Gmail contacts, and none of your Google+ contacts even if the plus.login scope is included in authentication. So if you want to work with Google+ contacts you will still need to use the people.list method of the Google+ API. And then you might as well use the people.get method of the Google+ API to get the rest of the information as well. The one benefit you get with people.get in the new API, is that any private information that has been added via Google Contacts will be displayed along with the Google+ profile information.

No more GData!

And after all my complaints one positive thing to say as well. If you've been using the old GData Contacts API you should switch to this new API asap. I think everyone who has been forced to work with GData will be happy to never see it again ;)

---

So to summarize my thoughts:

Great replacement for the old Contacts API, not really adding much value when working with Google+ contacts.

Curious to see what further features (if any) are planned for this API.

The Photos Dilemma

While the new Google Photos has some pretty interesting features for users (and several problems as well which I won't discuss here) the situation for developers wanting to do anything with photos gets increasingly depressing. Let's have a look at a little bit of history of how things evolved, where we are today, and what I would wish for the future.

In the beginning there was Picasa

Picasa Web Albums which is still available today comes with a fully-fledged API  with read & write access to fully manipulate and organize photos. Admittedly the old GData APIs aren't the nicest to work with compared to modern APIs, especially for client-side applications in JS, but the API still does its job today.

Probably the most useful API calls for read-access, since the documentation can be a bit confusing:

Request a list of albums:
https://picasaweb.google.com/data/feed/api/user/{{userid}}

Info about one album:
https://picasaweb.google.com/data/entry/api/user/{{userid}}/albumid/{{albumid}}

List photos in an album:
https://picasaweb.google.com/data/feed/api/user/{{userid}}/albumid/{{albumid}}

Along came Buzz

Here's a blog post for those who still remember the good old times:
http://googlephotos.blogspot.co.at/2010/02/photos-in-google-buzz.html

Google Buzz didn't really change much about how Picasa Web Albums and the associated API worked, it mostly seemed like Buzz was using the API itself to achieve all the features.

One feature that was introduced was the concept of "Photos from Posts" that automatically created special albums in Picasa for each post with photos you shared to Buzz. Those albums could be recognized in the Picasa Web Albums API with the <gphoto:albumType>Buzz</gphoto:albumType> tag they had assigned in the album description.

Funny enough photos shared directly in posts on Google+ today still generate "Buzz"-albums.

On the plus side...

With Google+ we got a new UI for managing photos that in many ways still is more cumbersome to use than the old Picasa Web Albums UI. But the album and photo IDs matched so it was easy to use the Picasa Web Albums API for programmatic managing of your Google+ photos

https://plus.google.com/.../6155360510478436241/6155360509668083954

https://picasaweb.google.com/data/.../6155360510478436241/.../6155360509668083954

https://picasaweb.google.com/...#6155360509668083954


With Google+ the new concept of sharing albums to circles was introduced. Those albums would show up with <gphoto:access>private</gphoto:access> and you could (and still can) retrieve the information about what people and circles albums were shared with by requesting the acl of an album:
https://picasaweb.google.com/data/feed/api/user/{{userid}}/albumid/{{albumid}}/acl

This would show information like this:

<entry>
  <gAcl:scope type='group' value='...'/>
  <gphoto:nickname>Photo Share Test</gphoto:nickname>
</entry>

<entry>
  <gAcl:scope type='user' value='...'/>
  <gphoto:user>116...</gphoto:user>
  <gphoto:nickname>Scarygami Test</gphoto:nickname>
</entry>

Google+ also introduced Instant Upload (or Auto Backup as it is called) creating a new automatic album with the <gphoto:albumType>InstantUpload</gphoto:albumType> tag. As with "buzz" the "InstantUpload" name stayed in the API even after the name was changed in the front end

At the Drive-In

Things started to get a little bit weird with Google Drive integration.

It began with the feature to show (some but not all) photos stored on Google Drive in the Google+ Photos UI, with each Drive Folder that contained photos getting their own album.

Those albums wouldn't show up when requesting the list of albums from the Picasa API, but you could request some information and the photos inside if you copied the album ID from the corresponding Google+ URL (https://plus.google.com/photos/.../albums/{{albumId}})

Things got even more confusing when Google(+) Photos were added to Google Drive. This allowed you to add a folder to your Drive which would include all the photos you uploaded and shared on Google+ sorted by year and month. You can then go ahead and re-arrange/edit the photos as you want, but... the sync is one-way and one-time only, meaning that changes done on Google Drive won't be reflected back to Google Photos and you only get the originally uploaded photo in Google Drive without any changes that you might make in Google Photos at a later point.

You can access those photos using the Drive API using the files.get and files.list methods, and you also have write access using insert/update/patch methods, and the Drive API being one of the newer discovery-based APIs is much nicer to work with than the antiquated Picasa API. But it won't help you in managing your Google+ Photos since the data isn't synced, and there is no indication whatsoever in the file meta-information that the files originally came from Google+. The photos in Google Drive also have completely different IDs than the ones you could use in the Picasa API, they are completely decoupled.

New and shiny?

And so we reach the present with the new Google Photos UI to replace the Google+ Photos UI.

Since there are several essential features missing, like the possibility to add geotags, I've been thinking about creating some extensions/scripts to do some of the things via the Picasa API. The problem is that Google Photos invented completely new IDs for photos and album that don't match the corresponding IDs in the Picasa API, even though the photos and albums still show up there.

The Picasa IDs show up nowhere in the page source so they could be parsed, and the Google Photos IDs don't show up anywhere in the Picasa API which makes finding a matching photo to work with in the Picasa API nearly impossible. You could parse some meta information (like date/filename) from the Google Photos page and try to find a match in the Picasa API but that is (a) bound to break regularly as the Google Photos page gets updated and (b) potentially requires a lot of API requests until you get where you want. But that seems to be the only possibility at the moment to get some programmatic access to your photos, or you could completely forget about Google Photos and continue using Picasa Web Albums and the API to manage your photos, only using Google Photos for uploading/backing up/editing/sharing photos.


Talking about sharing: with Google Photos the main way of sharing albums is to create a "secret link" that can be shared and viewed by anyone who has the link. That also means that all albums created with Google Photos now will always show up with <gphoto:access>private</gphoto:access>.

Sharing to Google+ still allows you to share to circles/people without creating the shareable link, and those access permissions are still visible in the Picasa API.

The Picasa API gets a little bit confused though when sharing publicly to Google+. Those albums show up as private in the API, and are shown as "Limited, anyone with the link" in the Picasa Web Albums UI. To make things a little bit more confusing those publicly shared private albums show up in the API even when not authenticated as the owner of the album:
Example of a public private album in the API

A New Hope

It's been almost 4 years now since a blog post about a potential Google+ Photos API was leaked.
While being read-only (as most of the Google+ API) this seemed like a promising start to replace the antiquated Picasa Web Albums Data API. But nothing ever happened there anymore and with Google Photos now getting decoupled from Google+ the Plus API doesn't seem to be right place to add such an API.

As discussed above the Google Drive API probably won't be a good home for new photos features either since there is no sync happening after the initial upload, even though it would be possible to represent most metadata related to albums/sharing/editing using custom file properties.

So it seems that we still have to wait for a separate photos API and try to use the Picasa Web Albums UI now as long as it is still working. The minimal functionality I would wish for is a way to map Google Photos IDs to Picasa IDs...

For lack of a better place you might want to star this feature request and maybe add a comment about what you would want to do with a Photos API and what features you are expecting to see in such an API.

Alternatively/additionally you can also use the feedback option in the new Google Photos site/app to tell Google you care about such an API.

Preparing for Polymer 1.0 - hangout-app

It must have been shortly after the Chrome Dev Summit in 2013 that I first started looking into Polymer. A lot has changed since then and most of the code I had written for the early versions of Polymer looks completely different now and went through a lot of re-write stages, but that's what you get for living on the bleeding edge ☺

Now Polymer has reached beta state with the 0.9 release and 1.0 is expected to come out at I/O so the time of breaking changes is slowly coming to an end. Some of my projects will probably forever remain like they are now, but I thought it was about time to start updating some of my more important (imho) elements, starting with my <hangout-app> element, that makes developing Hangout Apps easier.

While migration is generally easy thanks to migration guide there are still some things I've stumbled over (mostly because I flipped through the migration guide too quickly...)

No inheritance from custom elements (for now)

When I first created this element I had the idea (which seemed brilliant and completely logical at the time) to let people inherit from the hangout-app element to create their own hangout apps, so they could depend on the loaded property of the parent element to know when the Hangouts API is ready to be used:

With inheritance from custom elements not being supported (for now) I had to rethink this idea and I think the new solution is actually much clearer. You can now include the hangout-app element anywhere in your project and either wait for its ready event to fire or bind to its loaded property. Alternatively you can also include any of your markup as content of the hangout-app element and this content won't be rendered until the Hangouts API is ready to be used.

Conditional templates

The old <template if="{{condition}}">...</template> implementation removed/added DOM elements completely when the condition changed, which could have a negative effect on performance if used excessively, and I have to admit that I used it way too much in my projects, simply because it was easy to use and made the code somewhat clearer.

As I wrote a while ago the much better solution in most cases is to simply hide/show by conditional attribute binding to the hidden attribute: <div hidden$="[[!condition]]">...</div>

In the case of the hangout-app element I wanted to make sure that none of the content that might depend on the Hangouts API is part of the DOM until the API is ready, e.g. when using the hangout-shared-state element which tries to called the Hangouts API as soon as it is attached. For that reason I used the new implementation of conditional templates in the form of dom-if.

<template is="dom-if" if="[[loaded]]">
  <content></content>
</template>

This new implementation by default adds the content the first time the condition becomes true and afterwards only shows/hides the elements as necessary.

Layout attributes > Layout classes

I completely missed this part of the migration guide and was very surprised when my layout didn't look the way I expected it to.

The change from attributes to classes is easy enough though, just make sure to include PolymerElements/iron-flex-layout in your dependencies.


That's it for now, more coming as I upgrade more of my elements ☺

Google Sign-In 2.0 - Server-side

There have been a couple of questions lately about server-side access when using the new Google Sign-In functionalities, so I've put together this article to cover some possible use-cases.

User verification

Probably the simplest case is when you only want to verify on the server-side who the currently signed-in user is, e.g. to load user-specific data/settings for them. For this you can use the most basic sign-in implementation, securely send the ID token to the server and use one of the Google API Client Libraries to verify the token and get user information from it.


On the client side you wait for the sign-in success event to trigger, get the id_token from the authenticated user and send it to your server. You should always send the id_token via HTTPS for security reasons. On the server side (in this case using Python with Flask) you use the Google API Client library to verify the id_token and then use the information you get in what ever way you need. Please note that in this case you won't be able to make calls to Google APIs on behalf of the user. Here's the information you can get about the user from the id_token: I would highly recommend to read this article about ID-Tokens.

Optional server-side offline access

If you offer a web-service that will do something on behalf of the user while they are not online, I would recommend to make this an opt-in service after the user has signed-in.

E.g. if your service offers sending news to a user via the Google Glass Mirror API, they could sign-in to your website first, pick the news categories they are interested in and then "flip a switch" to enable "offline access".

For this you would have the normal basic sign-in flow on the client-side. You can then use the ID token as before to check if the user already has offline access authorized (i.e. you have credentials stored for their user ID already). If there is no offline access yet you can display an extra button to go through the grantOfflineAccess flow to get a one-time code which can be exchanged for access and refresh tokens on the server side. On the server-side you can then use the client-library to exchange the code for credentials that can be stored to act on behalf of the user at any point. grantOfflineAccess will always cause a pop-up to show for the user requesting offline access. This is the only way to get a refresh token, also in case you lost a previous one.

Necessary server-side offline access

If your service won't work without offline access (would be curious to hear your use-cases here) and you don't want your users to go through two sign-in steps, things get a little bit more difficult on the client-side (while you can still use the same server.py as above). You can't use the default sign-in button for this, since this flow always runs without granting offline access. Instead you have to use your own custom button (make sure to create it following the branding guidlines) which calls grantOfflineAccess.

For "old" users that come to your website again calls gapi.auth2.init will initalize an immediate sign-in flow which you can catch with the isSignedIn listener to check for existing credentials as before (just in case you lost them). For "new" users the grantOfflineAccess flow will return a code which you can exchange as above, and at the same time authenticate the user on the client side as well (calling your isSignedIn listener).

I hope this answers some of the questions you have, feel free to comment if you have more :)