Post on 15-May-2015
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