then you're a developer interested in working with
google products using their APIs.
More specifically, their APIs that use google data protocal.
So what is the google data protocol you might ask me.
Well before I can answer that I have to go through
some background information.
I'm assuming here you're familiar already with
the technologies of HTTP and XML.
Now for a long time, websites have been looking at
an alternative way of distributing their content
in a more computer friendly way.
Computers are not very bright so they need
a little help understanding our information as we see it.
So, let's look at a simple example, such as a blog site.
So a blog site has a number of news articles that
are displayed in a big list and they have a summary,
a title, who wrote them, when they wrote it.
So it's basic information.
How might we represent this in a computer friendly way?
Well, the first attempt to solve this problem was RSS
but the thing I'm talking about today is
the atom syndication format.
Atom is a XML based approach to describing the data
on these websites and making it easy for computers
to parse this information out.
So at the basic level you have a feed element
that contains multiple entries and each entry will have all
the metadata associated with the post on this blogsite.
Well that's great because now we have a compact way of
describing all the content on this blog.
But what if I want to create a program that edits this blog
and not just reads it
well i could create an entirely new mechanism to do
this and have it be drastically different than this feed
mechanism we've already described or
I could try and re-use it.
Well if i'm going to re-use this format
that describes my post all nicely in XML.
How would I transmit this data to the server?
Since these posts are already retrieved using HTTP,
we can just use HTTP to edit and delete this content
as well as create new content as well.
So great we can reuse what we already have and just make use
of other verbs in HTTP like put, post, and delete
and we have now a full cycle way of managing blog content
by just editing the feed basically.
Well what if it doesn't have blog entries?
What if it's not a blog? What if it's something like
a calendar or a spreadsheet how would i represent that data?
Well
you could try and do it in a new way
Or you could try and use this atom method again.
And if you use the atom method,
that's what google data tries to do.
So,
let me show you an example of
what an atom feed looks like.
Atom feed is XML
like what we said before and it contains entries.
Each feed has its own metadata as well as each entry.
You'll also notice that each entry has a unique identifier
that makes it distinct from all other entries on the site.
As well as some information used to edit it.
So,
once we take this and make it into
an editable form we call we call this
the atom publishing protocol.
And the atom publishing protocol extracts each of these entries
and turns them into resources.
Now these resources can either be a traditional text resource
or they could be a media resource such as an image file and video.
It also uses reuses the HTTP requests that we've already
discussed to manipulate this data and then it uses
the HTTP response codes in order to
tell if this operation was successful or had errors
or requires authentication.
Now this is what's usually referred to as
a restful protocol that uses the restful semantics
in order to modify these resources and each request is therefore
independently of each request and doesn't require
any additional context like a session to know what to do.
So here we have an example post of what it is to create
an entry on the blog using AtomPub
and you'll notice there is some authorization,
there is some other bits of metadata but basically
all we're posting is the atom entry
just like what we would get on the atom feed.
Once we have posted this, this bit of data we have created
this entry and we get back the entry as we created it
with some additional members such as an edit link
in case you want to modify it and we also get back
some kind of version string.
in this case, you see there is an "Etag"
which uniquely identifies the specific revision of this post
The 201 response code is used to indicate that
this content was successfully created on the server.
So now what is google data? How do I use it?
This abstract way of looking at atom feeds.
Well, what would you need if you wanted to represent
something that wasn't a blog post in atom?
Probably some custom XML that describes these entities.
represent abstract ideas that come across many APIs such as
what is a location? what is a time?
what is a contact? Things you don't want to have to
reinvent each time you're specifying a new API
or working with a different product.
So once we have this XML that fits nicely
into the Atom model. Since atom allows you
to extend its XML. What else might you need?
Well, there are some things like a query language
as part of google data. Google data basically allows us
to fill in the cracks between what atom pub tries to accomplish
and what we would like to accomplish using them as APIs.
So as I already mentioned, there is some form of
authentication that we already need to have in order to work
with google services and tie in to google accounts
and we also have some way of restricting what kind of content
that you are trying to access using this feed
and then we need some way to handle conflicts just in case
two people are trying to add the same information
And then we have these common elements to express
what this information is that we're working with.
And we had some other niceties as well
that are not part of the atom specifications
such as batch processing and media support.
So when we're making a query on an atom feed
or google data feed in this case, what is it?
Well basically it's just a URL that contains
enough information to tell us what kind of entries
we are to expect.
So first here, we have a URL that describes
all of the documents
in someone's docs and spreadsheets account.
And maybe all we really care about is
what spreadsheets they have.
so the second URL here is very similar to the first
but it uses a category query to restrict only
the spreadsheet document types in the result set.
and lastly of course we can retrieve just each
individual entry and the information associated with them
by passing a URL that contains some sort of document key.
The nice thing about google data
is that it has consistent features across all of
our API such as alternative output formats
like Json and RSS in case the software you're
working with natively consumes those formats.
It also has this Authentication model
that we'll talk about that allows you to
authenticate users to their google account
and securely access their data.
We have created a number of client libraries
for many languages that parse all this XML and
atom data into an easy to use object orientated model
that you can manipulate directly in the
language you are comfortable with.
and we also provide some protocol customizations like
I've said for things that atom hasn't tackled yet
such as batch processing.
In case you want to do a number of operations at once.
So as you can see, there are a number of google data APIs
out there for a number of popular google products
such as google calendar, google spreadsheets, picasa and youtube.
So you can now access data in any one of those products
using the same semantics that I'm describing to you.
So for example, lets go through
a simple way that I might as a programmer
interact with the google calendar API
so first I'm going to need some way of authenticating
this request that I'm going to be making.
So I have two options here.
One is AuthSub and the other is ClientLogin.
ClientLogin is meant for desktop based applications
that can have the user input their credentials directly
and then make their request to google's servers
where as AuthSub is intended to allow third party websites
to re-direct users to google's login page and then
re-direct back to the website in question
so both of these are going to give your program
some kind of token that you can pass along with
your request and make it an authenticated request.
So first let's see what we would have to do
to retrieve all the events in someone's calendar.
well it's very simple, all we are doing is
pulling down a feed passing along our credentials
and making this authenticated request.
So when we get it back, we get a two hundred okayed,
it means this request was successful
and we get back an atom feed that says some information
about the calendar such as this Mr. Test User's calendar
and he is based out of the Pacific time zone
But as you notice in this feed, he didn't have any calendar
events currently on his calendar so he is a very lonely person
and so maybe we should invite him to lunch.
Well here I am demonstrating how we can create an event
on his calendar,
by using the post semantics of HTTP.
So all we're really doing is creating an Atom entry
and then sending it to the feed.
So as you can see, we set the start time,
eleven-thirty is time for lunch at google
we set some information about it in description
and we're using this category, this kind of event
so people know this is an atom entry
representing a calendar event. so once we create it great,
we get a 201 created response
which means it was added to his calendar successfully
and we get back that same entry except now
you'll notice there is an edit link inside of the atom entry
which allows us to go back and make modifications
and there is a long ID there in red which distinctly
identifies this specific event and then you'll notice there
is a version string in blue which represents
this revision of this event which is of course
the first one since we just created it.
But you notice in this we forgot to set
where this location is occurring in,
Mr. Test User isn't always very bright,
so we had better tell him where it is
we had better edit this thing.
So now we are going to use put to edit
the event we just created.
You notice we are putting to the edit link
that we just saw in the previous slide
So here we are making this request to the edit link
with that specific revision string that we just used
and then we are passing our authentication information
and all we're doing is putting the same Atom entry
except now we are adding the bottom here in blue
the where element of specifying that google is
based out of Mountain View in California
So now that request has gone through, we get an ok back
and now you can see the latest form of the event
as on his calendar
and it has all the details he needs to find us
and he can come eat lunch with us, that's great
but maybe we don't really like Mr. Test User,
he kind of talks to much
and there is a reason that no one ever invites him to things
so we are going to delete that event on him
before he sees it hopefully.
And so here, to delete the event all we really need to do
is issue a delete request with the edit URL
we just got back from the updated form
Now notice I said the edit URL from the one we just got back
If we use the original edit URL that we edited the event with,
then that would already not work anymore since that
blue string at the end, that version ID would be
different than it is now.
But since it is the correct one, we get back a 200 OK.
Now if we had used the previous one,
you would see a 409 conflict error there
instead of a 200 OK. Which meant that there is now
now a newer version of event on the server than the one
that we are trying to delete.
So now that we have seen the fifteen minute rapid fire
walk through of how to use google data using specific things
you've got the basic idea of what google data is
and how it works on the basic level of XML and using HTTP
But perhaps like most people you don't want to construct
all this XML yourself. You might be more interested in
the high level client libraries we support in your language of choice.
So now what you should do is go to code.google.com/apis/gdata
to find out more and download the client library of your choice