Intro to Web APIs andthe Google+ API

Barcamp Phnom Penh 2011

Phnom Penh, Cambodia

Guy Flysher

About me

● Developer in the Emerging markets team.

● Joined Google in 2007.

● Previously worked on Social graphs,Gmail and Google Accounts.

● Currently work on SMS products (Chat SMS, G+ SMS and more to come...)

● G+ profile: http://gplus.to/GuyFlysher

The Google+ API(s)?

When people say the Google+ API they can sometime mean:

1. The +1 button.

2. The hangouts API.

3. The actual Google+ API :)

Agenda

● Part I: What are Web APIs?�○ Explanation and examples.○ How to enable Google APIs.

● Part II: The Google+ Web API

● Part III: OAuth and Web APIs

● Part IV: Client Libraries

What are Web APIs

● As the name implies they are APIs based on the web.

● Requests are made via HTTP requests.

● Responses return as JSON.

● Can be implemented in any language that supports HTTP requests.

● If the request was successful the HTTP status code is set to 200, otherwise another code will be returned along with a description of the error.

What is JSON?

● JavaScript Object Notation.

● Comprised of key value pairs.

● Easy for people to read.

● Easy for machines to parse.

JSON example

{ "myLabel": "my value", "image": { "nestedLabel": "another value" "anotherNestedLabel": "ok, got it." }, "collectionOfObjects": [ { "nestedLabelAgain": "first value", }, { "nestedLabelAgain": "second value" } ]}

A Web API call request:

GET https://www.googleapis.com/plus/v1/people/102947238809719640943?key=AIzaSyB4g0MY3zsLInJHa-qbDg0rbyCWak05hmI

A Web API call response:

{ "kind": "plus#person", "id": "102947238809719640943", "displayName": "Guy Flysher", "tagline": "A legend in his own mind", "gender": "male", "aboutMe": "No matter who began or first commenced it, I&#39;m against it!", "url": "https://plus.google.com/102947238809719640943", "image": { "url": "https://lh5.googleusercontent.com/<removed to fit slide>" }, "urls": [ { "value": "https://plus.google.com/102947238809719640943", "type": "profile" }, { "value": "https://www.googleapis.com/plus/v1/people/102947238809719640943", "type": "json" } ]}

(Some of) Google's web APIs

Analytics Blogger Books Custom Search

Cloud SQL Cloud storage Google+ Buzz

Identity Toolkit Moderator Orkut Places

Search for Shopping Tasks Translate Audit

Page Speed Latitude URL Shortner And more!

Enabling access to Google APIs

● Enabling access to the different Google APIs is done via the Google API console.

● Can be found at: https://code.google.com/apis/console/

● Also used to enable Oauth access (more on that later).

● Gives you an API key (remember the example before?)

● Lets do it together.

Agenda

● Part I: What are Web APIs?�

● Part II: The Google+ Web API

● Part III: OAuth and Client Libraries

● Part IV: Client Libraries

Google+ Web API overview

Currently the API allows access to three things:

1. People○ get○ search○ listByActivity

2. Activities○ list○ get○ search

3. Comments○ list○ get

Google+ Web API overview - People

● getGet a person's profile (requires the person's user ID) - Returns a "person" resource.

● searchSearch all public profiles - Returns a collection of "people" resources (+ a few more details).

● listByActivityList all of the people in the specified collection for a particular activity (+1/Reshare) - Returns a collection of "people" resources (+ a few more details).

People get example

GET https://www.googleapis.com/plus/v1/people/102947238809719640943?key=AIzaSyB4g0MY3zsLInJHa-qbDg0rbyCWak05hmI

People get respone:

{ "kind": "plus#person", "id": "102947238809719640943", "displayName": "Guy Flysher", "tagline": "A legend in his own mind", "gender": "male", "aboutMe": "No matter who began or first commenced it, I&#39;m against it!", "url": "https://plus.google.com/102947238809719640943", "image": { "url": "https://lh5.googleusercontent.com/<removed to fit in slide>" }, "urls": [ { "value": "https://plus.google.com/102947238809719640943", "type": "profile" }, { "value": "https://www.googleapis.com/plus/v1/people/102947238809719640943", "type": "json" } ]}

Google+ Web API overview - Activities

● listList all of the activities in the specified collection (currently only public) for a particular user - Returns a collection of "activities" resources (+ a few more details)

● getGet an activity (requires the activity's ID) - Returns an "activity" resource.

● searchSearch public activities - Returns a collection of "activities" resources (+ a few more details).

Activities search example

GET https://www.googleapis.com/plus/v1/activities?key=AIzaSyB4g0MY3zsLInJHa-qbDg0rbyCWak05hmI&orderBy=recent&query=snooker

Activities search response

Too big to fit in a slide...

so...

Play around with the API online:

http://code.google.com/apis/explorer/

And the result of the example.

Google+ Web API overview - Comments

● listList all of the comments for an activity - Returns a collection of "comments" resources (+ a few more details)

● getGet a comment (requires the comment's ID) - Returns a "comment" resource.

Comments list example

GET https://www.googleapis.com/plus/v1/activities/ z12pgdeqosedtdqtt22cshljesigjfxs5/comments?key=AIzaSyB4g0MY3zsLInJHa-qbDg0rbyCWak05hmI

Result

Agenda

● Part I: What are Web APIs?�

● Part II: The Google+ Web API

● Part III: OAuth

● Part IV: Client Libraries

Applications acting on behalf of the user

● Some applications need access a user's product data (e.g. Calendar meetings)

● Some applications need to perform actions on behalf of the user in a product (e.g. set up a meeting).

● How does the application prove to the product (in this case Google) that it is allowed to act for the user?

○ User gives the application their password?■ This is bad, why?

The solution: OAuth

● OAuth is an open standard for authorization.

● Allows users to share their private resources (e.g. photos, videos) stored on one site with another site without having to hand out their username and password.

● The user is prompted by Google to give the application the permissions it is asking for.

● If the user agrees Google gives the application a "token" with which the application can act on behalf of the user.

http://web-apis-slides.appspot.com/demo

How does it work?

● You (your application) sends the user to a special URL asking for the permissions you want:

REDIRECT https://accounts.google.com/o/oauth2/auth? client_id=685953454903.apps.googleusercontent.com& redirect_uri=https://mydemo.com/oauth2callback& scope=https://www.googleapis.com/auth/plus.me& response_type=code

Confirmation page

If the user agrees...

https://mydemo.com/oauth2callback?code=4/P7q8W92a-oMsCeLvIaQm6bTrgtp7

Google redirects the user to:

If the user doesn't agree, Google redirects to the same URL with no code parameter (but with an error parameter).

Exchange the code for OAuth2 tokens

POST /o/oauth2/token HTTP/1.1Host: accounts.google.com

code=4/P7q8W92a-oMsCeLvIaQm6bTrgtp7&client_id=685953454903.apps.googleusercontent.com&client_secret=Au4-Kcj1TPv0ycmNbjNV_esF&redirect_uri=https://www.example.com/back&grant_type=authorization_code

Send a post request:

Exchange the code for OAuth2 tokens

HTTP/1.1 200 OK

{ "access_token": "1/fFAGRNJru1FTz70BzhT3Zg", "expires_in": 3920, "refresh_token": "1/6BMfW9j53gdGImsixUH6kU5RsR4zwI9lUVX-tqf8JXQ"}

We get back a JSON response:

Using the OAuth token

In Google+ for example, we can now use the "me" identifier:

GET https://www.googleapis.com/plus/v1/people/me?key=AIzaSyB4g0MY3zsLInJHa-qbDg0rbyCWak05hmI&access_token=1/fFAGRNJru1FTz70BzhT3Zg

This will return the profile of the user this token was issues for.

Agenda

● Part I: What are Web APIs?�

● Part II: The Google+ Web API

● Part III: OAuth

● Part IV: Client Libraries

The great news...

You don't need to do all this work:● Prepare the HTTP API calls● Parse the JSON response● Prepare the OAuth2 requests (including refreshing the access

token).

Google has client libraries for using the Google+ API (as well as the other APIs) for:

● .Net● GWT● Java● Objective C (Iphone)● PHP● Python● Ruby

Using the Google+ Java client library

// This sample assumes a client "plus" object has been created.

Plus.People.Search searchPeople = plus.people().search();searchPeople.setQuery("Jenny");searchPeople.setMaxResults(5L);

PeopleFeed peopleFeed = searchPeople.execute();List<Person> people = peopleFeed.getItems();

// Go over all the results...

Using the OAuth2 Java client library

// Get the OAuth2 code.public void doGet( HttpServletRequest req, HttpServletResponse resp) {

// Generate the URL to which we will direct users. String authorizeUrl = new GoogleAuthorizationRequestUrl( 685953454903.apps.googleusercontent.com, // App ID https://mydemo.com/oauth2callbackurl, // Redirect URL https://www.googleapis.com/auth/plus.me) // Scope .build();

// Redirect the user so that they can allow us access. resp.sendRedirect(authorizeUrl);

return;}

Using the OAuth2 Java client library (2)

// Get the OAuth2 tokens.public void doGet( HttpServletRequest req, HttpServletResponse resp) { String oauth2Code = req.getParameter("code"); if (oauth2Code == null) { /* User did not allow us access */ }

// Exchange the code for an access and refresh tokens. GoogleAuthorizationCodeGrant authRequest = new GoogleAuthorizationCodeGrant(TRANSPORT, JSON_FACTORY, CLIENT_ID, CLIENT_SECRET, oauth2Code, CALLBACK_URL);

authRequest.useBasicAuthorization = false; AccessTokenResponse authResponse = authRequest.execute(); ...

Using the OAuth2 Java client library (3)

... // Save authResponse.accessToken and authResponse.refreshToken // in a database somewhere to be used for this user whenever // we need it.

// If the access token has expired, get a new one. GoogleAccessProtectedResource access = new GoogleAccessProtectedResource(authResponse.accessToken, TRANSPORT, JSON_FACTORY, CLIENT_ID, CLIENT_SECRET, authResponse.refreshToken);

access.refreshToken(); // access.getAccessToken() will contain the new token.

����������!

Q&A

Learning more

Google+ API:https://developers.google.com/+/api/

Google API client libraries:https://developers.google.com/+/downloads

The Plus Java client library docs:http://goo.gl/ojaLM

OAuth 2 in Java:http://code.google.com/p/google-api-java-client/wiki/OAuth2Draft10