Gregorio: Hi, I'm Joe Gregorio.
I work for Google in developer relations.
And today, we're gonna be talking
about the Atom Publishing Protocol.
So let's begin.
This is an intro to the Atom Publishing Protocol,
and if you want to know more details,
you can go and read RFC 5023,
which you should do, um, if you're interested,
because I'm not gonna cover all of the details in here.
This is just an overview.
So just as syndication started with just weblogs,
the Atom Publishing Protocol was originally designed
just for weblogs.
And that's the motivating example we're gonna use today.
But just realize that it can be applied to other areas.
So let's go and look at a feed in the Atom syndication format.
A feed contains one entry inside of it
per weblog entry.
And, because it's XML,
it's in a machine-readable format.
And so in the aggregation case,
uh, newsreader's gonna go and pull that feed,
and look for new entries.
And those new entries show up at the beginning of the feed,
and give you the-- really, the metadata
about that updated entry.
So if you're going to design a protocol--
and this is what we have with the Atom Publishing Protocol--
You really need to do four things.
You would want to be able to create new entries
on a weblog.
You'd want to be able to retrieve any new entries,
or old entries.
You would want to update entries that already exist.
And lastly, you would want
to delete entries out.
So if you look at syndication right now,
as far as building a protocol,
really, we already have retrieve done.
Right, 'cause I can go to the URI where that feed lives,
do a get, and get the latest things.
Here's the fundamental idea of the Atom Publishing Protocol,
and that is any changes you would make to a feed
are gonna be reflected in the weblog.
Uh, for various reasons, though, you probably don't want
to use the same exact feed
that you would put into an aggregator
as you would for editing.
You may have drafts that you're working on,
and you would want those drafts to be available for you to edit,
but you really don't want those going out
before they're allowed to be seen in the public.
So we're gonna differentiate.
There's going to be, uh, the aggregation feed,
and what we're gonna be talking about today
is the collection feed.
We have retrieve.
We're already basically a quarter of the way done
with the Atom Publishing Protocol.
We can retrieve. How about creating?
What--what would we do to create?
Well, in the Atom Publishing Protocol,
it's the simplest thing you could possibly think of.
We take an Atom entry,
and we post it to the URI of the collection feed.
That's just an entry.
There's no surrounding feed element around it.
So post that,
and that gets added to the feed.
Like we said before,
this change to the feed will also get reflected
in the weblog.
All right, so we're, in essence,
halfway done with the Atom Publishing Protocol.
So we have Create and Retrieve,
and the other two parts are Update and Delete.
So let's go back and look at that entry that was added
to the collection feed.
When you create a new entry,
the server will add some other elements
to that entry.
In this case, what you're seeing here
is the edit URI,
and every entry that gets created will have it.
and that's the URI by which you're going to update,
delete, and retrieve that entry.
So let's cover the simplest case first,
which is DELETE.
This is actually just--
You're going to send a simple HTTP delete message
to the URI of that entry.
And that's it.
There's no body that goes along in that request.
Just a DELETE.
Once that DELETE gets received by the server,
that entry gets removed from the feed.
And like we said before,
That gets reflected in the weblog.
That weblog entry goes away.
Okay, so we've got Create, Retrieve, and Delete.
The last thing we need is Update.
So at that edit URI,
you can actually do a GET,
and get the full entry.
And you will need to do that, because according
to the publishing protocol specification,
the entry that sits in the collection
may not be the full entry.
It might be abbreviated in order to keep bandwidth down.
So I can go to that edit URI,
do a GET, and get the full representation.
Now, if I wanted to update what was going on,
I could actually modify that entry on my client,
and then put it back to that exact same URI.
And so in this case, I have updated the title.
I do a PUT, and now that entry will be updated.
And that'll get reflected in the feed,
and on the weblog.
So we're done.
We've covered all four parts
of what you would want out of a publishing protocol.
Creating, retrieving, updating and deleting entries.
Well, we're at least done as far as text is concerned.
What about media?
What if I wanted to add an image or a sound or video?
How do you do that in the Atom Publishing Protocol?
Really, it's the--
Again, the simplest possible thing you could imagine.
We take your media,
and you send that in an HTTP post request,
again, to the same exact collection URI.
That adds it to there.
Media is slightly different, in that when I post media,
I actually create two distinct resources.
I'm gonna create a resource with the URI
that is the actual media itself,
like the image.
And then, there's going to be
what's called a "media link entry."
That's the metadata about the picture.
The title, the time it was posted, etc.
We can see those two resources
when we look at the media link entry
that gets added to the collection.
The edit link points, like I said,
to the media link entry,
and you can manipulate that
just like we did previously with entries.
I can do a GET on that, to get the entry,
I can to a PUT on it to update it,
and I can send it a DELETE to remove it.
And then there's the edit media link.
That supports GET and PUT.
So if I wanted to update that image,
I would change the image, and put the image--
and that's an HTTP PUT--
to the edit media URI.
If I wanted to update
the title of that image,
I would update--change the media link entry,
and put that entry-- HTTP PUT--
to the edit URI.
And, like I said before,
if you wanted to remove that media,
you would send a DELETE.
Again, no body, just send a DELETE
to the edit URI.
Now, this is actually a slight distinction.
That's the way you end up removing the metadata
about the image, and the image itself.
You only need to send one delete,
and that'll remove both of them.
So in the examples we've done so far,
I've assumed that there's just one collection,
and we're adding our entries
and our media to that same collection.
That might not actually be the case.
That might actually be a little difficult to organize.
So we may actually break it down
into multiple collections.
There may be a collection for entries,
and then there may be a collection
for all of your images.
Or there may be a link blog.
You can break things down that way.
So how do you discover which collections are available?
That's where the service document comes into play.
That contains information about all of the collections
that a service supports.
So if you look at a service document,
you'll see that there are collections grouped together
into workspaces.
Um, and now here,
we're looking at a collection
that just takes entries.
And right there, in that HREF,
that is the URI for our collection.
Now we know what to do with that.
We could post to that
to add new things to that collection.
There's actually two collections in this service document,
and the second one is a media collection.
And those accept elements
tell you the types of media that you are allowed
to post to that collection.
In this case, it can accept JPEGs, PNGs and GIFs.
Okay, so that finishes our overview
of the Atom Publishing Protocol.
If you want to learn more, you can always read RFC 4287,
which is the internet standard for the Atom Syndication Format.
You can also read RFC 5023,
which is the IETF standard for the Atom Publishing Protocol.
In addition, a good video to follow this one
is Jeff Fisher's "Intro to Google Data,"
which is available also on YouTube.
Uh, that covers how Google has implemented
some of these standards.
And finally, you can always go to code.google.com/apis/gdata,
which covers all of the documentation
for Google's APIs.
Thanks, and have fun.