Google I/O 101: Google APIs: Getting Started Quickly

ANTONIO FUENTES: Hi, my name is Antonio Fuentes and I'm a
product manager at Google.
Part of my job is to make sure that developers have a great
experience when building applications
that use Google APIs.
Today, I will show you some of the tools and services
available to Google developers to get started quickly,
including how to sign up and use an API, how to make simple
calls and calls that use authentication, and how to get
started building code in minutes.
We will start with a simple background after which we will
go through the steps that any developer would go through
when building an application that uses Google APIs.
We will actually build a very simple application to
illustrate these steps.

We will talk about the tools available to explore the
functionality of Google APIs, tools available to learn about
authentication, how to obtain credentials to identify your
application.
We'll also talk about how to manage access and traffic for
your application.
And finally, we will use a simple example to start
writing code.
First, a little bit about who this webinar is for.
This is a beginner 101 style webinar.
We assume that you know our program.
The example we will use is in Python, but the principles
apply to any programming language.
We will target a developer who has little experience coding
with Google APIs, but who likes to dive in and learn by
experimenting.
It is also important to make the distinction of which APIs
this webinar applies to.
Google has about 100 public APIs.
We're going to focus on the RESTful APIs.
REST has become a standard for surfacing data and is well
understood in the developer community.
These APIs are simple to use and are built on the HTTP
protocol and the API surface resources that can be
manipulated with HTTP verbs.
And resources are nothing but a document living at a URL.
In the case of these Google APIs, these documents are
written in JSON.
Many API Google offers are RESTful.
Some examples include Google+, Calendar, Blogger, Latitude,
and many others.
In our example, we will be using the Google+ API.
So let's say I would like to build an application to
display my Google+ public posts and information in them.
In today's example, we will focus on requesting the data
from Google+.
But you can later use the principles you learned with
any other Google RESTful API.
One key distinction is that I want to build an application
that can access the data from the end user who is logged in.
So, for example, if I go to my Google+ profile and I type in,
I am excited about IO, and share it as a public post,
those are exactly the kinds of posts that I would want to
retrieve with my application.
Let's look at the basic steps we will follow to build an
application that uses a Google API.
First, I would probably want to know if Google+ has an API,
and what it looks like.
So we will start by exploring the
functionality of Google APIs.
Since I want to access data for the end user of my
application who is logged in, we will also want to learn
about authentication.
Next, we will learn how to obtain credentials and
identify my application before making API calls.
We will also learn how to manage access and traffic for
the application.
And finally, we will write and run a simple application.
So let's start with the first step.
How do I learn about Google APIs?
Does Google+ even have an API?
And what does that API look like?
The first tool we will use is the Google Developers Portal.
Google Developers is a central location, a one-stop shop,
where you can not only learn about Google products,
services, and tools, but also things like developer events,
hangouts, news, use cases, success stories, and so on.
Today, we will be using the Google Developers Portal to
learn about Google APIs.
And in particular, the Google+ API.
Read the documentation for Google APIs, explore API
semantics, and try Google APIs and get
started coding quickly.
This is what the Google Developers Portal looks like.
It contains news, links to documentation, hangouts, and
many other resources for developers.
You will notice that on top of all the information available
on the main page, there's a search box.
And this is Google, after all.
I'm going to click on the search box and type in the
name of the API that I'm looking for.
In this case, the Google+ API.

I see that there's an API for Google+, and that there's a
link to the documentation.

The documentation for the Google+ API is structured the
same way as the documentation for other RESTful Google APIs.
There is a main landing page where you can learn about
general concepts that apply to the API, such as quota,
authorization, API calls, data formats,
pagination, and so on.
On the left nav, you can find links to the resources exposed
by the API.
Here I can see that the Google+ API has People,
Activities, and Comments resources.

I will select the People resource to look at the
documentation for that particular resource.
I see that there is a Get, a Search, and a List By Activity
method for the People resource.
Each method has a documentation page, and this
is how I will navigate to them.
I'm going to click on the Search method
for the People resource.
And the documentation for the Search method tells me the
HTTP request format to make a request.
It also tells me about parameters, and how to define
and request body if one is required.
It also tells me what the response of the API would look
like and what all the parameters mean.
Better yet, the documentation shows me code examples in a
variety of languages that I can simply copy and
paste into my code.
The documentation also allows me to make my own API calls by
providing a tool right there on the documentation.
I'm going to search for my own profile to see how this works.
I'm going to enter the name of my profile that I've created
for this presentation and make an API call using this tool.

Uh-huh, I see that as expected, the API returns JSON
structure using the response parameters I saw in the
documentation.
I can even click on the link in the response to look at the
Google+ profile it returns.
And I see that it is my profile.
Now, what if I want to see the other methods
available for this API?
I can find them using the left nav on the documentation.
I see that every resource available for this API has a
series of methods.
Alternatively, I can use the APIs Explorer, which is linked
to on this main page.
The APIs Explorer is the second tool
we'll be using today.
The APIs Explorer is a tool that allows you to, among
other things, list all available RESTful Google APIs,
explore methods, require
parameters, including checking.
which of those parameters are required.
Make API calls using an interactive tool, and actually
examine the HTTP response.
And send authenticated request calls that fetch
data owned by a user.
The Google APIs Explorer was built using the Google APIs
Discovery Service, which we introduced last year.
This is what the APIs Explorer looks like.
It has a directory-style listing of all the Google
RESTful APIs.
Using the APIs Explorer, I will locate the Google+ API,
which is the one I'm using in my application.
The Explorer will immediately show me all of the resources
and methods available for that API.
Let's try to search for public activities.
I would go to plus.activities.search method
and perform a query.
The Explorer shows me a list of parameters I can supply to
make this API call.
And it also tells me which of those are required.
In this case, I'm performing a query to search all public
activities on Google+ that match a query string.
And the query parameter is required.
So, for example, if I click and search for Google IO and
execute this request, I see that the Explorer tells me the
request that was sent and the JSON object with the response
from the API.
If I need to narrow it down to my own activities, I can try
the list method in the APIs Explorer.
plus.activities.list will list all activities in the
specified collection, which is in this case, activities for a
particular user.
The documentation for the Google+ API indicates that to
list your public activities, you can use a parameter me.
And you can use public for the collection.
So let's try that and see what happens.
When I click on Execute, the APIs Explorer will tell me
that something has not worked.
The Explorer is indicating to me in several ways that
there's a problem with my request.
First, it is telling me that I need to be authenticated in
this red bar.
And that I need to authorize my request using OAuth 2.
Second, the API itself has thrown a 401 HTTP response
code and the JSON object specifying the error.
It looks like we need to pass our credentials using OAuth 2
so that the Explorer can fetch data for my
activities on my behalf.
So let's go ahead and try to make a call with the APIs
Explorer that uses OAuth 2.
I would first switch to make authorized calls using this
convenience switch on the right.
The Explorer will ask me to select OAuth 2 scopes.
These are used to specify levels of access that will be
granted to the Explorer when it accesses end user data.
I see that there are two possible scopes that can be
used for this API call.
One for the Explorer to have access to my + profile and one
for the Explorer to have access to my email address.
I will select the default option.
You can always look up the documentation for an API to
see which scopes are declared by an API, or read the OAuth
protocol documentation for more information.
When I click on Authorize, I see that now I get a consent
screen asking for end user permission for an application.
In this case, the Explorer.
The Explorer wants to have access to my data.
When you build applications that make API calls to fetch
end user data, your end users will see something like this
if you use the OAuth 2 protocol.
If I allow access and make the same API call again, I will
see that now the APIs Explorer actually fetches my public
activities from my profile.
To recap where we are up to now, we have learned about two
tools to explore the functionality of Google APIs,
the Google Developers Portal and the Google APIs Explorer.
So we just did an authenticated API call.
What if we want to learn a little bit more about
authentication?
Let's start with an impossibly brief summary of OAuth 2.
In a nutshell, OAuth 2 is a protocol that allows you to
build applications that access data on behalf of a logged in
user without requiring their passwords.
The protocol consists of a few steps.
An application makes a request to Google to show the end user
a consent screen, just the way we saw with the APIs Explorer.
On consent, Google gives access credentials back to the
application.
The application then uses those credentials to request
end user data.
And it's important to know that the credentials expire or
can be revoked at any time by the end user.
There's good documentation on OAuth 2 on the Google
Developers site.
And there's a session on Google I/O that dives deeper
into how it works and how you can use OAuth 2 in different
platforms and use cases.

Luckily, the Google Developers Portal also has a tool to help
you understand how OAuth 2 works if you want to make an
authenticated API call.
This tool is called the OAuth 2 Playground.
And it allows you to understand the OAuth 2
protocol, and also navigate the steps to make an
authenticated call using an interactive tool.
You can actually make API calls using this tool and
examine the HTTP response.
Let's try to recreate the steps we just learned about
with the OAuth 2 Playground.
First we select which APIs we want to use.
In this case, the Google+ API.
This will select an appropriate scope for me.
If we recall from the few steps ago, a scope defines the
level of access that an end user will consent to when
given access to an application.
When I click on Authorize APIs, we're performing step 1,
which is the application.
In this case, the OAuth Playground sending a scope and
requesting an authorization code.
And see, I see a consent screen similar to the one I
saw from the APIs Explorer.
This time the OAuth 2 Playground is asking
permission to access your Google+ profile using the same
scope as before.
Once I allow access, the OAuth 2 Playground will actually
show me the HTTP requests made to the OAuth endpoints at
Google and their response.
In this case, an authorization code.
The next step is to exchange the authorization code for an
access token.
The OAuth Playground allows you to do that with a single
click of a button.
And it will also show you the HTTP request that was made, as
well as the response.
In this case, an access token.
The OAuth 2 Playground actually allows you to make a
call with those tokens.
Using the same example as before, I'm going to list my
public activities from my Google+ profile using the same
URI I used before.
If you recall, all we have to do is substitute me and public
for the collection.

Once I send that request, I see the
same response as before.
Unlike the APIs Explorer which provides a directory of
methods, parameters for an API, the OAuth 2 Playground
focuses on understanding the steps in the OAuth 2 protocol.
When we used the Explorer, all of these steps to request and
exchange tokens were implemented behind the scenes.
Your client application would have to do the same if you
write it from scratch.
The good news is that the Google Client Libraries do all
this work for you, and implement these steps under
the covers.
This is one of the many reasons we strongly recommend
using the Client Libraries.

All right, we just saw how OAuth 2 Playground allows you
to learn about authentication.

What if you want to build an application and make a request
using your own credentials?
When building an application that uses Google APIs, you
need to obtain credentials from Google which you can
embed in your API calls.
These credentials allow you and Google to know who or what
is invoking the API.
And in some cases, can be used in the OAuth 2 flows to
identify both the invoking application and its end user.
Among other reasons, this enables you to manage
application access.
Using the APIs Console, which we'll talk about in a moment,
you can generate OAuth 2 client IDs and API keys.
Which you can then embed in your application to invoke
authenticated Google API calls.
Use OAuth 2 client IDs in your browser, desktop, or
mobile-based applications to allow it to call Google APIs
and request data on behalf of its user.
In our example, you would use the OAuth 2 client ID if the
application caused the Google+ API to fetch
an end user's data.
Use API keys if your application does not require
end user data or consent.
For example, you might use API keys in an application that
involves the Google Translate, or Custom Search, or the URL
Shortener APIs.
The APIs Console is a management tool for using
Google APIs.
Here, you can take a variety of actions in addition to
generating OAuth 2 client IDs and API keys.
For example, you can establish a relationship with Google and
identify your application.
You can sign up to use Google APIs and review
their terms of service.
You can obtain credentials you can embed when
you make API calls.
And you can provide billing details to use paid APIs, such
as those that are part of the Google Cloud platform.
Now back to my application.
I'm going to use the Google APIs Console to register an
application.
I'm going to give a name and a simple logo.
And I'm going to sign up to use the Google+ API.
And last but not least, I'm going to obtain a client ID to
make API calls using OAuth 2.
When you go to the Google APIs Console, you'll notice that
you're asked to create a project.
Projects are used to identify applications and assign
attributes to those applications, such as
credentials, the team working on them, traffic controls, and
others as we will see.
I'm going to create a new project.
The next step is to sign up for the Google+ API.
To do this, I simply turn on the switch for
that particular API.
But notice how I can use multiple
APIs in a single project.
When I sign up for this API, I must accept the terms of
service before proceeding forward.
I will only be required to do this once as a developer, even
if I create other projects that use the API.
Also, many Google APIs are under a standard set of terms
of service, which means you only have to
agree to these once.
OK, now I need to get credentials for my
application.
The API Access tab on the left side of the console allows me
to do just that.
So if I go to the API Access, you will see that I can create
OAuth 2 client IDs or API keys.
In this case, I will create an OAuth 2 client ID since I want
my application to access data on behalf of an end user.
When I do that, I will be required to provide
information about my application.
Providing a name and [INAUDIBLE]
logo is enough for this step.
So I'm just going to call it my killer app and give it a
funny logo.

Now I'm asked which type of client ID I need.
As we saw before, there are different types of client IDs
depending on the nature of my application.
I will choose an installed application since my code
lives in my own server.
When I do that, the system will generate a client ID and
a client secret for me.

Now we have learned how we can use the Google APIs Console to
obtain credentials and identify your application.
We will now learn how to manage access and traffic for
this application.
And why do you care about access and traffic controls?
First, you may want to restrict who can make calls
with your credentials.
This is your first line of defense against leaked or
stolen credentials.
Depending on your use case, the console allows you to
configure, for example, which websites can invoke Google
APIs directly from a web browser if you're working with
a browser key.
Which JavaScript origins are allowed to make authenticated
calls using your OAuth 2 client ID.
The allowed redirect URIs to be directed to after an end
user consent screen.
Second, you can throttle the amount of traffic your
application handles.
This allows you to cap the number of API calls initiated
by the end user.
This is particularly important if you want to limit specific
end users from consuming all of your available API quota.
Or if you want to cap the number of API calls your end
users make against the paid Google API.
For example, the Google Translate for which you're
paying for.
So let's go back to the APIs Console to work with this
simple example.
I'm going to go back to the OAuth Playground
we were using before.
One of the advantage of the OAuth 2 Playground is that it
allows you to enter your own credentials, essentially to
pretend that the OAuth 2 Playground is your own
application, and to see what your end users would see on a
consent screen.

So the OAuth 2 Playground provides a place where I can
enter my own credentials.
And it's telling me that in order for the flow to work, I
need to make sure that the OAuth Playground URL is on the
list of allowed redirect URIs for my project.
This means that once Google is done presenting the end user
with a consent screen, it will redirect to that URL.
And I'm going to copy it.

Now I can go back to the APIs Console and generate a client
ID for a web application since the OAuth 2 Playground is a
web application.

I will add the OAuth 2 Playground URL to the list of
valid redirect URIs for this particular key.

Now, the APIs Console has generated another client ID
and another client seeker for me.
In this case, for a web application.
We can copy now our own client ID and client secret and paste
it into the OAuth 2 Playground.

So I'm going to take the client ID, paste it in the
space for it, and take the client secret and do the same.

Now we have a working application that uses our
credentials.
And let's look how I would configure traffic controls.
I can go to the quotas tab of the APIs Console and set the
per user limit for API calls that are made using my
credentials.
I see that the Google+ API allows me to do 10,000
requests in a day.
And that I can further scope that to a per user limit,
thereby allowing me to limit traffic for individual users
and Queries Per Second, or QPS, to limit individual users
from generating unwanted traffic and
consuming all my quota.
I will set the value to the default.

Let's go back to the OAuth 2 Playground and execute the
same steps as we did before.
I will select the Google+ API and authorize the scope.

And now I see a consent screen that is
presented as I expected.
But this time it has my application information
displayed to the end user.
Then, once I grant access, the application will continue to
make authorized calls on behalf of me.

I can continue with the steps as before and make an API call
the same way we did before.

And I see that the response looks the same as before.
But this time it's coming from the OAuth 2 Playground
pretending to be my application.
I can also use the Google APIs Console to check the traffic
for my application and the traffic
that's being generated.
I can do that by looking at the Reports tab.

The Reports tab contains useful information about usage
patterns for your application.
In this case, I see that a single API call, which I just
did, has been made using my credentials.
We have now learned how the APIs Console can help us
manage access and traffic for our application.

And now that we have explored a variety of tools and we have
signed up to use the Google+ API, let's build
and run some code.
Google makes it easy to get started coding when using APIs
by providing a variety of client
libraries in many languages.
Using Client Libraries has many advantages, and we
strongly encourage you to use them.
First, the libraries make it very simple to securely call
any RESTful API and manipulate the data without the need to
write any code to access the data surfaced by the API.
The Client Libraries also take care of
handling errors for you.
And most importantly, they handle all of the steps and
the OAuth 2 protocol that we learned previously.
Every time we introduce new features to Google APIs, the
Client Libraries are gradually updated to
include those features.

But let's not forget our original objective, we're
building an application to access the Google+ posts for
the user logged in using the app.
Going back to the documentation for Google+, the
client libraries are accessed using the downloads link on
the left nav.
The downloads page has a table with all the client libraries
currently available to use with Google APIs.
These Client Libraries are all open source and were developed
using the Google API Discovery service, which was the same
service used to build the APIs Explorer.
Let's click on the Python Client Library.

This will bring us to an open source project hosted on
Google that contains downloads, documentation, and
more for the Python Client Library for Google APIs.
I'm going to go ahead and install this Client Library on
my server, for which I would download a zip file provided
in the page.
Installing the Client Library is as simple as running a
single command.
I will copy this command for reference.
I'll also download the zip file.
Notice that when you install the Python Client Library, you
do not have to download the zip file.
But I'm only doing that to access some samples and
documentation included in the bundle.
I have downloaded the installation zip file and I
have placed it in a temp directory on my server.
Now that I have done that and extracted it, I can install
the Client Library using a simple command.

And that's it, the Python Client Library for Google APIs
has been installed on my server.
Getting a starter application running is just a matter of a
few simple steps.
We have already installed the client library, we need a
sample that works with the Google+ API and
is written in Python.
You can access samples from the search box in the Google
Developers Portal from the documentation for a particular
API, or from the open source project that
hosts a client library.
Let's try to find a sample on the open source project for
the Python Client Library.
If we go to the page, we'll see that
there's a link for samples.
And it will give a list of all Google APIs that have samples
in this client library.
By clicking on Google+, it'll show me the path for the
sample for Google+.
So let's look at that sample.
It says it loops over all the user's activities and prints a
short snippet.
There's a sample that does exactly what I need it to do
in principle.
I see that the sample comes under the
directory samples plus.
So let's go look for it.
So I'm going to go to my server and navigate to the
path where the sample resides.

And I see the sample.
Let's try to run the sample and see what happens.

No luck.
The sample application is telling us to please
configure OAuth 2.
And why?
Because the APIs making an authenticated call to fetch my
data and I have not supplied any application credentials.
Let's examine the file where we can specify our
credentials.
According to this instruction, it's clientsecrets.JSON.

When we look at that, I see that the sample has a space
where we can provide, within our own server, the client ID
and the client secret for our application, which we already
obtained when we signed up to use the Google+ API.

The Python sample from Google+, as well as many other
samples offered by Google, provides a convenient location
to make it easy to paste your credentials.
Let's see what happens when I paste my credentials in the
file that was provided.
I'm going to go to the APIs Console.

And as before, I'm going to copy my client ID and my
client secret.

This time I'm going to go to my server and paste it in the
provided file.

I'm going to start by pasting my client ID, and then paste
my client secret.

So let's try to run that sample again and see what
happens now that we've pasted our credentials into the
provided file.

The first thing you will notice is that, as we learned
when we looked at the OAuth Playground, your application
makes a request to access data on behalf of the end user.
And the end user can grant this access in a consent
screen, which we see here.
The consent screen shows data for my application and is
telling the user that my application is requesting
permission to know who they are in Google.

Once that request is granted--
and as we saw when we played with OAuth Playground, my
application will be given an access token that will
continue to use when making API calls on my behalf.
When I use the Python Client Library, I don't have to worry
about implementing any of the steps in the OAuth 2 protocol
since those are handled for me.
Let's run this code again.
The code, as we know, is fetching all my public
activities from Google+.
You will see that my application already knows who
I am, and it's making API calls using the same access
token, which it can do until I revoke it or it expires.
Let's look at the code in a little more detail.
To make authenticated calls, initiate an OAuth 2 flow with
the functions provided in the library.
All we do is provide the scope of the API we want to use,
which we can easily obtain from the documentation or the
OAuth 2 playground.
We're also specifying in the code the location of the file
that contains our credentials.
To make calls to the RESTful API using HTTP protocols, we
can use the HTTP lib 2 library to construct an HTTP object.
Then we can call credentials that authorize to modify my
new HTTP object, so that it can sign my request with OAuth
2 credentials.
And here's the beauty of the client library.
We can create a service object that knows how to talk to the
API by using the build function in
the Google API client.
We pass the name of the API we want to use and the version,
as well as the authorized HTTP object from the previous step.

And we're almost there.
The client library allows you to access collections in the
API by simply calling the name of the collection.
For the Google+ API, you can call service.people to access
the people collection.
The collection object that is returned has all the methods a
collection understands.
In this example, we're using the get method for the people
collection.
We can also pass parameters to the API call.

Here we see how we constructed another HTTP request object
that queries the activities collection
and the list method.
A call to service.activities.list does
not make the API call for me.
It only instructs an HTTP request object that contains
in it all the information required to make the API call.
If you want to execute the request, you
can just call execute.
Alternatively, you can gather a set of HTTP request objects
and execute them asynchronously.

When we execute this request, the API will return a JSON
response that will be converted to a Python object.
In this case, activities dock.
Any error code returned from the API
will erase an exception.
Again, all of these details are handled by the client
library for you.
So we just saw how we can use the client libraries for
Google APIs to write and run your code in minutes.
In summary, we just learned about some of the tools for
Google Developers to explore the
functionalities of Google APIs.
In particular, the Google Developers Portal and the
Google APIs Explorer.
Then we learned tools that can teach you about
authentication.
In particular, the OAuth 2 Playground.
Then we saw how to obtain credentials and identify your
application for which we use the Google APIs Console.
We also saw how we can use the console to manage access and
traffic for your application.
And last, we saw how you can use the Google Client
Libraries to write your code and get started.
For more information, you can type the names of the tools we
just covered in the Google Developers Portal in the
search box, or you can go to the links
provided on the screen.
There are several sessions that touch on how to build
applications that use Google APIs in Google I/O 2012.
In particular, there's a session that covers how to
build JavaScript applications that use Google APIs.
In addition, there's a session on how to optimize your code,
a session on OAuth 2 and identity and data access, and
a session on building Android applications.
Check the schedule for Google I/O for dates and times.
And thank you very much, and thank you for watching.