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
