Practical AtomPub Servers @ YAPC::Asia 2008

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

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)

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

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

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 Matrix of metadata and URIs URIs Metadata Simple and with data Rich and separated from data By servers AtomPub By clients Amazon S3

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

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

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

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

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

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 

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

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

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 

http://teahut.sakura.ne.jp	35
http://74.125.153.132	2
https://teahut.ddo.jp	1
http://www.slideshare.net	1
http://webcache.googleusercontent.com	1

Practical AtomPub Servers @ YAPC::Asia 2008

by Takeru INOUE on May 15, 2008

Accessibility

Categories

Upload Details

Usage Rights

5 Embeds 40

Statistics

Practical AtomPub Servers @ YAPC::Asia 2008 Presentation Transcript