Practical AtomPub Servers

takemaru

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

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

Data Model   Members

  Web Resources in usual sense   Entry Resources or Media

Resources

  Collections   Sets of Members   Retrieved in whole or in part

  Workspaces   Group of Collections

Collection

Member

Workspace

Members and Collections have their own URIs

Resources and Representations

in which there are several Entries

- Articles which are referred to a category - Images of an event

- An article in a blog - An image

Collection

Member (Entry or Media)

Feed Document

(XML)

Entry Document

(XML)

AtomPub (RFC5023)

Atom Format (RFC4287)

Web Resources

Examples:

Examples:

metadata

substantial data

Operations   Five operations: List + CRUD

  Determined by target (URI) and HTTP method

Operations against Collections Operations against Members

GET: Lists members in the collection

POST: Creates a new member (Member URI is assigned by the server)

GET: Retrieves a member

PUT: Updates a member DELETE:

Deletes a member

Operations in depth – Entry and Media Resources

  Entry and Media Resources   Two sides of the same coin

POST: Creates a new Member (substantial data)

Metadata: - Describes attributes of the data: date, author, etc. - Has a link to the data - Automatically generated as an Entry by the server

Entry link

PUT: Updates the Member

Metadata MUST be updated at the same time

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

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?

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

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

URIs \ Metadata Simple and with data Rich and separated from data

By servers AtomPub

By clients Amazon S3

Matrix of metadata and URIs

Amazon S3 (Simple Storage Service)   Metadata

  Placed in HTTP headers   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

PUT /yapc.asia/yapc2008.png HTTP/1.1 Content-Type: image/png Date: Tue, 15 May 2008 01:23:45 GMT X-Amz-Metadata: …

Example of HTTP request

Metadata

Data

URI

/yapc.asia yapc2008.png

AtomPub   Metadata

  Has its own URI and independent from data   Written in Atom entry

  URIs   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>

12345678.atom

12345678.png /images

Metadata: /images/123456578.atom Data: /images/12345678.png

Entry

Embedded AtomPub – Actually, this is AtomPub in usual sense

  Metadata   Has it own URI and independent from data   Written in Atom entry   Text/XML data can be embedded in metadata

  eg. atom:content element

  URIs   Determined by servers   Suggested by requests with Slug header

POST /blog HTTP/1.1 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> <author><name>yapc</name></author> … <content type=“text”>This is my first entry</content> </entry>

Example of HTTP request

Metadata

Data

URI suggestion

first_entry.atom

/blog Entry

Positioning AtomPub in RESTful services

AtomPub with Media resources Amazon S3 and embedded AtomPub

URIs \ Metadata Simple and with data Rich and separated from data

By servers AtomPub

By clients Amazon S3

Matrix of metadata and URIs

embedded

Slug header

12345678.atom

12345678.png

Entry

first_entry.atom

Entry

  Characteristics of AtomPub   With rich metadata and mainly controlled by servers   Can be changed by embedded content and Slug header options

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

⇒ If you choose AtomPub, go for Catalyst::Controller::Atompub

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

Can overwrite default behavior

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

  Stores resources to, or retrieves them from databases   Modifies the resources (optional)

  Constructs HTTP response and sends it to client

Your turn

by C::C::Atompub

by C::C::Atompub

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; }

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; }

Sample code – Changing default URIs

# 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; }

eg. /collection/20080515-012345-123456.atom -> /collection/joe/birthday.atom

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

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