1. Practical AtomPub Servers
takemaru

2. Outline
What’s AtomPub?

Data model

Five Operations: List + CRUD

Role of AtomPub servers

Better choose AtomPub for your Web service?

What’s the difference in RESTful services

Compared with Amazon S3 (Simple Storage Service)

Positioning AtomPub in RESTful services

Catalyst::Controller::Atompub

Makes you forcus on your task

Sample Codes

Summary


3. What’s AtomPub?
 What’s AtomPub?
Defined in RFC5023

One of REST instances

Web API for publishing and editing Web resources

Based on HTTP transfer of Atom-formatted representations

 Services using AtomPub
Google: GData, Blogger, OpenSocial

Microsoft: Live Platform

IBM: Lotus Connector

Mixi: mixi station API


4. Data Model
Workspaces
Members 

Group of Collections
Web Resources in usual sense 

Entry Resources or Media

Resources
Collections

Sets of Members Members and Collections have their own URIs

Retrieved in whole or in part

Collection
Member
Workspace

5. Resources and Representations
Examples:
Feed
- rticles which are
A
Document
referred to a category
(XML)
Collection
- mages of an event
I
in which there are
several Entries
Entry
Examples:
Document
- n article in a blog
A
(XML)
- n image
A
Member metadata
(Entry or Media)
substantial data
AtomPub Atom Format Web Resources
(RFC5023)
(RFC4287)

6. Operations
Five operations: List + CRUD

Determined by target (URI) and HTTP method

POST: Creates a new member
(Member URI is assigned by the server)
PUT:
DELETE:
Updates a member
Deletes a member
GET: Retrieves a member
GET: Lists members in the collection
Operations against Members
Operations against Collections

7. Operations in depth
– Entry and Media Resources
 Entry and Media Resources
Two sides of the same coin

POST: Creates a new Member (substantial data)
PUT: Updates the Member
Entry
link
Metadata MUST be updated
Metadata: at the same time
- escribes attributes of the data: date, author, etc.
D
- as a link to the data
H
- utomatically generated as an Entry by the server
A

8. Role of AtomPub Servers
List + CRUD operations

Supports publishing and editing Web resources

Assigns Member URIs when they are POSTed

Maintenance of metadata

Generates corresponding Entries when POSTed

Updates attributes when the corresponding data is PUTed or DELETEd

Others

Service description in Service Documents (not discussed in my talk)

HTTP processings: Authentication, cache, version control, and error handling

Compared with simple RESTful APIs, AtomPub servers have strong authority

9. Better choose AtomPub for your Web
service?
 Myths of AtomPub
AtomPub is a protocol just for blogging

 AtomPub is the best one to publish ANY type of Web
resources
 Which service is suited for AtomPub?
Text-orientd services, such as blogging and SNS?

File management systems including binary data?

Something else?


10. AtomPub is one of REST instances
AtomPub is one of the REST instances

Don’t choose AtomPub if your service is NOT RESTful

Compare AtomPub with other RESTful APIs if your service is RESTful

Common features of RESTful services (in my talk)

Addresses resources by URIs

CRUD resources by HTTP methods: GET, POST, PUT, and DELETE

Resource type is not an issue: plain-text, XML, images, videos, …

Data model of dataset including several items (see figure)

Set
Item

11. What’s the difference in RESTful APIs?
Metadata

Which kinds of metadata are needed?

Where are metadata placed?

URIs

Who determines resource URIs?

Other options

Search queries, representations, etc.

Comparing AtomPub with a contrasting API, Amazon S3
Matrix of metadata and URIs
URIs Metadata
Simple and with data
Rich and separated from data
By servers
AtomPub
By clients
Amazon S3

12. Amazon S3 (Simple Storage Service)
Metadata

/yapc.asia
Placed in HTTP headers

yapc2008.png
Line-by-line syntax

Always along with data in HTTP body

URIs

Determined by clients

PUT is requested with a URI to create a resource

URI
PUT /yapc.asia/yapc2008.png HTTP/1.1
Content-Type: image/png
Metadata
Date: Tue, 15 May 2008 01:23:45 GMT
X-Amz-Metadata: …
Data
Example of HTTP request

13. AtomPub
Metadata

Has its own URI and independent from data
 12345678.atom
Written in Atom entry

12345678.png
/images
URIs

Entry
Determined by servers

<?xml version=“1.0” encoding=“utf-8”?>
<entry xmlns=“http://www.w3.org/2005/Atom”>
<link rel=“edit”
href=“/images/12345678.atom”/>
<link rel=“edit-media”
href=“/images/12345678.png”/>
<content src=“/images/12345678.png”
type=“image/png”/>
…
</entry>
Metadata: /images/123456578.atom
Data: /images/12345678.png

14. Embedded AtomPub
– Actually, this is AtomPub in usual sense
Metadata

Has it own URI and independent from data

first_entry.atom
Written in Atom entry

Text/XML data can be embedded in metadata

eg. atom:content element

Entry
URIs

/blog
Determined by servers

Suggested by requests with Slug header

POST /blog HTTP/1.1
URI suggestion
Slug: first_entry
<?xml version=“1.0” encoding=“utf-8”?>
<entry xmlns=“http://www.w3.org/2005/Atom”>
<updated>2008-05-15T01:23:45Z</updated>
Metadata
<author><name>yapc</name></author>
…
Data
<content type=“text”>This is my first entry</content>
</entry>
Example of HTTP request

15. Positioning AtomPub in RESTful services
Characteristics of AtomPub

With rich metadata and mainly controlled by servers

Can be changed by embedded content and Slug header options

12345678.atom
first_entry.atom
12345678.png
Entry
Entry
AtomPub with Media resources
Amazon S3 and embedded AtomPub
Matrix of metadata and URIs
URIs Metadata
Simple and with data
Rich and separated from data
embedded
By servers
AtomPub
Slug header
By clients
Amazon S3

16. Better choose AtomPub for your Web
service?
 Services, which are suited for AtomPub
Metadata is represented in XML, especially in Atom Entries

Atom standard elements are required: author, category, copyright, …

 Linked to other resources: eg. a blog entry including pictures
 XML vocabularies are used in the metadata: OpenSearch, RDF, …
 Complicated data model is acceptable, or don’t use media resources
URIs are determined by servers

Or determined based on clients’ suggestions

I
f you choose AtomPub, go for Catalyst::Controller::Atompub

17. Catalyst::Controller::Atompub
A Catalyst controller class for processing AtomPub

Why controller?

AtomPub defines CONTROL flow for publishing and editing Web resources

Tested in AtomPub Interop

July 2007 at Tokyo

Nov 2007 on the Internet

Feb 2008 at Tokyo

Download from CPAN


18. Catalyst::Controller::Atompub
 Makes you focus on your task (eg. Model implementation)
Dispatches requests based on URI and HTTP method

Check cache or version of the requested resources (optional)

Validates requested Entry if exists

Determines a new member URI when POST
 by C::C::Atompub
Stores resources to, or retrieves them from databases

Modifies the resources (optional)
 Your turn
by C::C::Atompub
Constructs HTTP response and sends it to client

Can overwrite default behavior

19. Sample code – Creating resources
# Attribute :Atompub(create) is required
sub create_entry :Atompub(create) {
my($self, $c) = @_;
# URI of the new Entry, which was determined by C::C::Atompub
my $uri = $self->entry_resource->uri;
# datetime, which was assigned by C::C::Atompub
my $edited = $self->edited;
# POSTed Entry, an XML::Atom::Entry objcet
my $entry = $self->entry_resource->body;
# Creates the new Entry
$c->model('DBIC::Entries')->create({
uri => $uri,
edited => $edited->epoch,
xml => $entry->as_xml,
});
# Returns true on success
return 1;
}

20. Sample code – Listing resources
# Attribute :Atompub(list) is required
sub get_feed :Atompub(list) {
my($self, $c) = @_;
# Skeleton of the Feed, an XML::Atom::Feed objcet,
# was prepared by C::C::Atompub
my $feed = $self->collection_resource->body;
# Retrieve Entries sorted in descending order
my $rs = $c->model('DBIC::Entries')
->search({}, { order_by => 'edited desc' });
# Adds Entries to the Feed
while (my $member = $rs->next) {
my $entry = XML::Atom::Entry->new($member->xml);
$feed->add_entry($entry);
}
# Returns true on success
return 1;
}

21. Sample code – Changing default URIs
eg. /collection/20080515-012345-123456.atom -> /collection/joe/birthday.atom
# Changes Edit URIs, that is URIs for Member resources
sub make_edit_uri {
my($self, $c, @args) = @_;
# Default URIs for Entry (and Media) resources
my($edit_uri, $edit_media_uri) = $self−>NEXT::make_edit_uri($c, @args);
# Modify the URIs as you like...
# Returns modified URIs
return ($edit_uri, $edit_media_uri);
}
# Changes Collection URI
sub make_collection_uri {
my($self, $c) = @_;
# Constructing the new Collection URI as you like...
# Returns the Collection URI
return $new_uri;
}

22. More…
Many sample applications are found in samples/ directory

MyAtom: Most simple AtomPub server

MyBlog: Complicated server with Media resources

OurBlogs: Single Collection class provides multiple Collections

gihyo.jp gives detailed articles

Search “gihyo.jp atompub server”

Sorry, written in Japanese


23. Summary
What’s AtomPub?

Data model

Five Operations: List + CRUD

Role of AtomPub servers

Better choose AtomPub for your Web service?

What’s the difference in RESTful services

Compared with Amazon S3 (Simple Storage Service)

Positioning AtomPub in RESTful services

Catalyst::Controller::Atompub

Makes you forcus on your task

Sample Codes

Summary
