March 30, 2020
Google+ Platform Office Hours for March 7th 2012: REST API Overview

Google+ Platform Office Hours for March 7th 2012: REST API Overview


JENNY MURPHY: Hello
there everyone. Welcome to another session
of the Google+ platform Office Hours. Today we’re going to be doing an
overview of the REST APIs, which are a major component
of the Google+ platform. So this is another one of
those kind of one-on-one sessions to get you started on
developing with REST APIs if you’ve been interested in them,
but haven’t had a chance to develop on them yet. I’m your host today. I’m Jenny Murphy. I’m a developer programs
engineer here at Google. I spend a lot of
my time working on the Google+ platform. And the REST APIs are actually
the area I spend most of my time focusing on. And I have a couple people
who’ve joined me today. ALLEN FIRSTENBERG: Hi there. I’m Allen Firstenberg. I am a developer
from New York. Mostly I develop with the
Hangout API, but I also do some work with the REST API. MARTIN: Yeah, hi. I’m Martin from Germany. I’m studying computer
sciences. And I do a lot with the
REST API as well. JENNY MURPHY: Great. And thanks a lot for joining
me guys, otherwise I’d be really lonely here. So what we’re going to be doing
today is I’m going to be going through some slides. Oh no. And some demos of one of
our starter projects. And then I’m going to be
fielding some questions that you guys ask. And if you have any questions,
there’s a link to the announcement thread
that should be on the post you’re seeing. And just go ahead and put your
questions there, and hopefully we’ll get to them. So without further ado, I’m
going to dive in and start telling you about
the REST APIs. So the Google+ platform,
RES API edition. This little drawing below here
with all the cool arrows on it, that’s what we’re going
to be talking about. It’s the Google+ platform. And the REST APIs
are part of it. I guess the red arrows because
they kind of have the center ring, kind of a core
part of it. So what is the Google+
platform? Before I can really dig into the
REST APIs, I kind of have to explain how they kind
of hang together with everything else. The Google+ platform has a few
major components to it that are largely independent
but can work together in many cases. So there’s the REST APIs which
are the way you access data that is on Google+. So if you’re writing another
application and you want to read data from Google+,
this is how you do it. There’s also the plug-ins, which
are probably the ones you’re most familiar with,
because you’ve probably seen the Plus One button in
a lot of places. And hopefully you’ve seen the
badge elsewhere also. These go on web applications
and are a way that you can actually insert data into
Google+ via shares. And finally, below are the
really fun Hangout apps. And these allow you to write
interactive applications that are a real-time collaboration
between people who are participating in a Hangout. Today we’re going to be focusing
on the REST APIs and how you can access data
that’s already on the Google+ platform. Yeah, today we will
rest, REST APIs. So what are the REST
APIs really about? The REST APIs are primarily
about accessing public data on Google+. It allows your applications that
you write, whether they be web applications, mobile
applications, whatever, to be able to access the data that’s
on Google+ that users have created, via a kind of
language-agnostic, platform-independent way. In addition to public data,
there is a very small amount of private data you can get to
right now, which we’re always looking to expand. Or we’re always investigating
new cool things we can add to it. And all of that data, which is
private to users, is protected via OAuth 2.0. So this allows your users to
authorize you to access data on the Google+ platform that
is not necessarily public. That covers the API surface. But there’s a lot more to the
REST API offering we have. We have recommend client
libraries. These are client libraries that
we built that make use of the REST API. And the intent is to make things
a lot easier for you. So when you’re developing, you
don’t have to worry about a lot of the boilerplate stuff. And I’ll be describing those in
a little more detail later. Client libraries, they’re cool
and all, but whenever you work with a new framework, or a new
client library, or something like that, there’s
a learning curve. And we have some start-up
projects which make that learning curve a lot easier to
get over and get you something running right away. And I’ll be demoing one of
those at the end of this discussion. So let’s get back to
t API surface. What can you access? I mentioned public data, but
what does that really mean? You can see up close on the
screen, this is just a picture of an orange that I posted that
got a little bit of buzz. I guess it got people excited. But I just used it to play
with the API, because it demonstrates the things
you can get to at the REST API right now. One of the things you
can access is public fields of profiles. So any fields that I’ve made
public on my profile are going to be exposed via
the REST API. In addition to that, you can
see public activities. So the activity contents, any
objects that are attached to that activity, +1s, that kind
of information, the re-share account, we can access all of
that about existing activities on Google+, assuming they’re
public activities. And finally, one other entity
you can access right now. You can access the
comments that are associated with an activity. So if the activity is public,
you can see all the comments, because those comments are
public by association. So now that you know what you
can access, how do you actually learn how to use it? The reference docs are a great
place to both start and then to return to as you’re doing
your development. And one of the things that
makes our reference docs really cool is they’re not just
a list of methods, and attributes, and that
kind of stuff. We have code samples in some
popular languages, specifically Java, Ruby,
Python, PHP. Little code snippets that show
you how to use it in a realistic case for each
one of our methods. And then, if you want to dive in
right away, we have this A Explorer that’s embedded right
into the reference docs. So all you have to do is scroll
down, and you can use it right in front of you. So let’s take a look at it. Here are the reference docs. If you just go to
developers.google.com/+/api, you’ll land here. Let me zoom in so you can
see it a little better. They’re organized in,
kind of, the way you’d expect, by entity. And within each entity, we list
the methods you can run. We’re going to look at people
again, because it’s a really simple one. And when you get here, you’ll
see the kind of stuff you would expect. You’ll see the structure of
the URL, because it’s a RESTful API, the list
of the parameters. And here’s the interesting
stuff. We have little code snippets. Let me get it focused
on there. We have code snippets in each
one of those languages. And it will keep track of your
favorite language, the last one you selected. But you can pretty
easily switch. Oops, the menu shifted over,
probably from the browser zoom, but now it’s
a Python snippet. Pretty cool. And right below that is
the API Explorer. So we can really
easily try it. So let’s try the
peopleget API. So I’m going to go over and grab
my profile ID, which you can get from the URL of
your Google+ profile. Then we can execute it. And below this little window
as it appeared, the REST representation of my profile
on Google+, all those public fields. This is a really cool way to get
started and start to see what kind of information you
have access to on the APIs. But it’s also really useful when
you’re troubleshooting later on, kind of as a sanity
check, to see what’s really coming back from the API. And I end up using the API
Explorer a whole lot when I develop on the APIs. It’s one of those tools that
kind of never gets old. So previously I was talking a
lot about accessing the public data via that API Explorer field
on the reference docs. And so far, all I really
talked about is that public data. But I mentioned some private
data before. So you can actually access one
piece of private information via the Google+ REST
APIs, and that is somebody’s identity on Google+. So you have your third-party
application. And you want to be able
to, for example, access their profile. This is cool and everything,
but if they have to type in their user ID, it doesn’t
really work. So what we allow you to do
is use a placeholder, me. And me can be anyone,
usually your user. And then, your user is prompted
with an authorization page that allows them to
authorize your application to convert that me into
your profile ID. And then you can use that, as a
developer, to access all of the other public information
that they’ve created. So let’s take a look
at it in action. I’ll zoom in a little more,
so you can see better. This is the people-get method
we were looking at earlier. Same window on the
reference docs. I’m down here at the API
Explorer in the bottom. There’s a little switch
on the right side we were ignoring before. It’s the OAuth dialogue. So we hit this, and it’s going
to allow us to use OAuth to authorize with the user, who
is, in this case, me. So I’m going to be authorizing
the API Explorer to find out who I am on Google+. OAuth uses scopes to determine
the specific permissions you are requesting. In this case, plus set
me is equivalent to my identity on Google+. So let’s hit Authorize. It pops up an authorization
prompt, which is actually in a different window. But I just authorized it. You’ll have to trust me there. Now that we’re authorized,
we can do execute. And we can see below
that I have done a request for people/me. And what I’ve gotten back is
my profile on Google+. So I’ve now given the API
Explorer access to my identity on Google+. And, you know, what the API
Explorer does is just dumps the response. So it sent it back to me. So I can see it. Pretty cool isn’t it? So what actually happened there
behind the curtain, I hit some buttons and it looks
kind of like some magical stuff happened. So what happened there is the
client, which is the API Explorer, sent me an
authorization request. And that was the pop-up that you
actually didn’t see. And I told it that it
could have access. I granted it authorization to
find out who I am on Google+. In the background, the API
Explorer then sent that authorization grant, in the form
of a special code, over to an authorization server at
Google, which responded with an access and a refreshed
token. And this happened behind
the scenes. So your application will have
to do this when you’re doing the OAuth flow. After that, the API Explorer
used that access token that it received to hit the resource
server, the Google’s API server for the Google+ APIs, and
it got back the protected resource, in this case my public
fields on Google+, which reveal my identity. And this is just kind of a
small, little sliver of all the stuff that OAuth
2.0 provides. It has all sorts of cool
different flows for installed apps, and client-side apps
like JavaScript apps. But you really don’t need
to worry about this too much right now. It’s really important that you
understand how this works later on as you’re developing
your application. But you don’t need to worry
about it to get started, because our client libraries
take care of a lot of this stuff for you. They’re pretty neat. So what all do they
help you do? They help take care of all that
OAuth stuff’, all that token exchanging, and
that kind of stuff. And also doing, like, exchanges
for refreshing the token when they time out,
that kind of stuff. So it takes a lot of that
burden away from your application. It also handles all the
marshaling and unmarshaling of all the data that’s provided
by the API. Caching is another important
feature that the client libraries provide, which can
save you lot of time developing those features
yourself. There’s actually a whole bunch
of other stuff I’m not going to list here that the client
libraries provide. And we have them for a lot of
different languages and platforms. We have them for
.Net, Go, GWT, Java, JavaScript, Objective C
for OIS developers, PHP, Python, and Ruby. They’re all at different
levels of completeness. A lot of them are in what we
call beta, which as you know, means it’s pretty polished
already. We recommend that when you’re
developing using the Google+ APIs or any other Google
APIs, you check out the client libraries. They’ll save you
a ton of time. You can get them at
developers.googl e.com/+/downloads. So client libraries are great. But with any framework or
client library there’s a learning curve. And we want to get you started
really fast, right? So what we’ve done is
we’ve packaged up these starter projects. And the intent is to make
your awesome idea easier to get going. So what are the starter apps? The starter apps are really
simple applications that access the APIs using our client
libraries, and they implement a lot of our best
practices around how we do OAuth and how we use the API. So the idea behind this is you
can get running, you can get some base foundation of code
running that accesses the APIs, and then you can
hack away at it and make it your own. So it’s a great foundation for
whatever awesome project you want to do. We have them written for four
popular languages, Java, Ruby, Python, and PHP. Within those languages, we also
have them written for many platforms in many cases. For example in Java we have a
web application version that’s like a generic [UNINTELLIGIBLE]. We have one for App Engine,
because we love App Engine. We have a command
line example. And we have an Android
example. And you can also get them
at that downloads page. So let’s take a look at the
Java starter project. I’m going to shuffle some screen
sharing around and bring up a terminal. Let me zoom in a little bit
so you can see better. There we go. I’m in a place where I’ve
downloaded the Google+ Java starter and unzipped it. It comes in as a file,
pretty easy to use. And we’re going to take a look
at the command line one, because that will involve
less window switching. But they’re all just
as easy to use. So let’s go to the command line
directory and just take a look at what’s in there. There really aren’t that many
files in this directory. There’s like 15 files
or something. And some of them are,
like, IDE files for the clips and stuff. The core of it’s really small. And actually there’s some
[UNINTELLIGIBLE] slot files in there too. There’s really not
a lot to it. So it’s really easy for you
to get started and then to understand what’s going on. There’s just not a lot of code
to look at, which is always great for examples. Let’s take a look
at the Read Me. The Read Me has the instructions
on how to use this project. So all we really have to do
is set up authentication. This walks you through going to
the Google API console and getting your OAuth credential
set up, because as a client of the Google+ APIs, you’re going
to have to set up a project and some other stuff. It’s pretty easy. It’s just a few clicks. And these steps will walk
you through it. Once you’ve done all that stuff,
all you have to do is take a few pieces of
information, your client ID, your client secret, and your API
key, and put them in this config doc properties file. So let’s go ahead and do that. Apparently I already have
it open in an editor. There we– Edit anyway. So there we go. Let’s go replace these things. I’ve already gone ahead and
gone and grabbed some credentials from the
API console to save a little time here. So I’m just pasting
them in now. Oh hey Allen. There’s two Allens. Oh, one times that. So I’m pasting the
credentials in. In general, never share the
client secret with anyone. I’m just sharing it now because
it’s a demonstration. And I’m going to be going and
revoking these credentials afterwards. So if you ever actually do leak
them out by accident, which happens, they’re pretty
easy to revoke. So now that we added those three
things there, if you go look at the Read Me again, it
says that once we’ve put them in there, all we have to do is
compile and exec, exec:java, because maven’s really cool. It does all the dependency
management stuff for us. So let’s go ahead and do that. So we’re compiling our
starter protect. This might take a little longer
the first time you run it, because maven has to go
fetch those dependencies. ALLEN FIRSTENBERG: Jenny, going
back to the keys, can you also discuss how you’re
going to be dealing with those keys if you’re distributing
something using JavaScript? JENNY MURPHY: Sure thing. So that’s the client side flow,
which is a little bit different than the
server side flow. I’ll be sticking to the server
side flow for the demo. But I’ll loop back when we’re
done and explain some of the differences between the client
side and server side flow. ALLEN FIRSTENBERG: OK,
great, thanks. JENNY MURPHY: Going back
to that terminal. Here we are. So now that’s it’s all
compiled, we run it. I’m actually going to switch the
screen share real quick to show you what it popped up. It opened Chrome and displayed
a OAuth window here. So this is what we missed before
on the API console. This is the application that,
you know, it’s told Google to pop up this [? OS flow ?] so
that I can allow it access. So I’m going to allow
it access. Because it’s command line and
not a web app, normally I’d use, like, redirects and stuff
to get this special code back, but we’re going to have
to use the very sophisticated copy and paste. So I’m going to copy from
there, go back to the terminal, paste that code in. And what we can see now
is a whole bunch of API calls happening. And that’s all the starter
project is. It’s really easy to get going. So we’ve now, even just pasting
in a few lines of code, just those keys, we
now have a running Java application that’s
using the APIs. So if I was building a command
line app or some other kind of service side Java app, I have
a really good foundation. Maybe I’ll merge the code I have
in already that’s going to use the APIs, or I’ll just
use this as a starting point. And that’s it. That’s a quick demo of
the Java starter app. It’s that easy to get going. Allen asked a good
question before. How is the client side
flow different? So client side applications
like ones that run in JavaScript on the web browser,
such as Hangout applications, which I imagine is why you’re
interested, they work a little bit differently. Because we have that client
secret, we can’t keep that client secret, we can’t expose
that to the user. Because then they will be able
to masquerade as our application. So for client side flow, what
we do is, there’s a few different components. We have a JavaScript origin,
which you set in the API console, which I guess I
can pull up real quick. Here’s a project in the
Google API console. This project is called
API project. And I’m showing you all sorts
of stuff about it, so I’m going to be clearing
it out later. But here we can see that I’ve
created some client IDs for applications. This one’s for web
applications. One of the things you’ll set
when you have a JavaScript application that’s going through
a different OAuth flow called the client side
flow, is you’ll set a JavaScript origin. And this is how we guarantee
that only your servers are running it. So you’ll put your domain
names here as well as redirect URLs. So this is where Google will
send the user back after they’ve completed
the OAuth flow. So you’ll just set these to
your applications or the domains of your applications. And that will guarantee that
only you are allowed to send someone to the OAuth flow, and
only you are allowed to get the redirect back. And then there’s a couple of
other differences, because the client secret kind of gets
left out of the equation. And what you lose as a result is
you lose the refresh token. So that means you’re only going
to be getting these access tokens which only
last for about an hour. And to refresh them, instead
of doing a refresh flow as part of the OAuth spec, you’ll
actually just be going through the authorization flow again. So what you’ll be doing is
you’ll be bouncing off of a Google web page. So there will be kind of a
little redirect bump that happens every hour or so. And hopefully that
explains it. The easiest way is to, if you
really want to understand this well, check out the
JavaScript client. There’s a JavaScript starter
included too. And that will make it make
a lot more sense. Because most of the other ones
use the server side flow because that’s just more
common in general. Cool. So, that’s it for the– MARTIN: OK, so the
direct APIs– Oh, no, go ahead. JENNY MURPHY: I was just going
to ask if there were any more questions in the room before I
went to the [UNINTELLIGIBLE]? MARTIN: All right. Some methods return an ETag
field, though I think it’s for caching right? So it changes as soon as
something of the content changes, if I understand
it correctly. JENNY MURPHY: That is correct. So the ETag is– I’m trying to remember where
that came from in the spec. For example, the activities API
is an implementation of the activity stream
specification. So some of these tags are
hanging around from that. And I think that might be
one of those fields. So in general, in regards to
caching content, we recommend that you pay attention to all
the cache control headers and stuff you have set. So pay attention to those
first and foremost. The clients that we provide will
take care of that already. In addition to that, there’s
also the ETag, which is kind of the next level up on the
ability to see when things have changed. So if your writing an
application that’s kind of sucking down all the data,
you’re going to be pulling the APIs a lot. And what you can do is you can
use this thing called fields, the fields parameter, which
allows you to only pull certain fields back. So you get a much smaller
chunk of data. And you could only
look at the ETag. And then you can use that to
slightly more efficiently see, especially more bandwidth
efficiently, when something is changed to see if you need
to do the bigger request. MARTIN: And does the ETag
include all fields? So for example, if someone plus
ones an activity, does the ETag also change because
the plus one count changes? JENNY MURPHY: Yeah, the ETag is
unique for all the content within that response object. So anything that changes in
there will update the ETag. MARTIN: All right. JENNY MURPHY: Yeah. MARTIN: Thanks. JENNY MURPHY: You’re welcome. Cool. So I’ve seen a few requests on
there asking when we’ll have more extensive APIs available,
specifically write-access to the stream. We’re always working to expand
the APIs that are available. But we’re kind of
taking our time. We want to do this right,
so we’re being careful. Because a lot of us that had
built applications on other platforms before kind of
had the rug pulled out from under us. We really didn’t like that. So we want to make sure that
all the APIs we release are going to be sticking around. And we’re honestly still kind
of figuring out how we want some of these APIs to work,
because we care about a lot of things in addition to people
building awesome applications. We care a lot about
the quality of content on the stream. Google+ has a really high
quality content in the stream right now. We want to make sure that
stays the case. There’s a lot of
other reasons. But we’re still working on a
lot of this APIs, and once they’re available, we’ll let you
know when you’re good to go on them. But they’ll be awesome,
I promise. I also see a few comments in
the stream that are feature requests that don’t really
have to do with building software on the Google+
platform. They’re about things like
the iPhone application and things like that. Those are more feature requested
related to the Google+ product as a whole. So when you’re on Google+,
you’ll see a little Send Feedback link. It’s going to be in one of the
corners depending on what language you’re viewing
the page in. For these kinds of questions,
go click on that Send Feedback link. We do read the feedback. You may not get a response or
everything you post. But we’re definitely reading it. People are reading all of it. We’re aggregating it. And we are paying attention. And that helps us best
prioritize what stuff we’re implementing. Because there’s only so many
of us, so we have to prioritize the stuff
we implement. So definitely do
send feedback. We’re paying attention to it. And I see a couple of questions
about frozen plus-one counters. So I haven’t really been saying
a whole lot on this. I think there’s some forum
[UNINTELLIGIBLE]. I think I recognise some of
your names from the forum. I think I’ve talked to
you there before. We are working on this. We think we’ve resolved some of
the issues that should be related to, specifically,
discrepancies between the counter value and the values in
Google Analytics and Google Webmaster Tools. But if you’re still seeing
problems, I’m going to loop back and try and see if we
can get to the bottom. There might be more
than one problem involved in this situation. So we’re still rolling
out the first fix. Hopefully that will take
care of everything. And then if that doesn’t, I’ll
be looping back with you guys to make sure everything
is good. But just hang tight. This one might take us a little
while to figure out. It seems like one of those
complicated ones. ALLEN FIRSTENBERG: Buried in
one of the comments was a question that kind of talked
about the quota limits for the REST API. Do you want to talk about the
quota for it a little bit? JENNY MURPHY: Sure. As you may have noticed
recently, all of your applications out there that you
created which formerly had 1,000 free calls per day, now
have 10,000, a lot more. So we recently bumped
up the base quota. And that’s so that you guys
can get started doing development more easily. But we’ve got to understand
that especially when you launch applications, you’re
going to need a lot more quota, especially really
cool things. I’ve seen a lot of really cool
stuff out there recently. And I can tell that a lot of
them are probably using a lot of calls in the back end
to do their cool stuff. In the API console there’s a
link that allows you to ask for more quota. Those actually generate a ticket
that a lot of us in the team are looking
at, I included. So you’ll probably see a
response from me or one of my teammates not long after
you post it. We’re getting responses
much faster now. There was a time when we
were a little slow. And we’ve kind of ironed the
kinks out of our process. So we should get back to you
in a business day or two. We’ve been pretty good lately. We’re pretty much on
top of it now. So you should hear from one of
us, like, in a business day. And once you’ve done that,
depending on how much quota you request, we have to go
through a different process to get that quota granted to you. And this can take
a little while. This could take a week
potentially. So ha tight. You’ll get a response from us
telling you to hang tight. Please follow those
instructions. And continue polishing your
app or wording other co-applications. And we’ll be getting back
to you when we can give you more quota. But if you want the request
to go fastest– I forgot the most
important part. How do you make your
request go faster? If you’re requesting quota,
please include a link to a privacy policy that just tells
us what data you’re collecting, and what you’re
doing with that data, and retention policy, destruction,
all that kind of stuff. Just tell us what you’re doing
with the data and link to it on that little form. That’s the most important
first thing. Second one, have
a working demo. This is not always possible. Some of them require accounts
and that kind of stuff. If there’s an account that has
to be set up or authorized, please include information
about that account in the little comments box. And we’ll bounce back and forth
and get that worked out so that we can see
it in action. And we realize there’s some
applications that we can never see in action like, for example,
academic projects that are just pulling a lot
of data on the back end. And we’ll work with you to make
sure that we understand exactly what you’re doing. OK. So we’re actually going to be
taking next week off of the Office Hours probably. But we’ll be back
the week after. And we’ll have some really cool
stuff to talk about then. Happy hacking everyone. You know where to find us,
in the forum on Google+. We hope to see you there. Bye everyone, and thanks so much
for joining me guys and everyone else who asked
questions and anything. ALLEN FIRSTENBERG: Bye Jenny. MARTIN: Bye. JENNY MURPHY: Bye.

Leave a Reply

Your email address will not be published. Required fields are marked *