Introduction to AtomPub Web Services

Introduction to AtomPub Web Services
Ben Ramsey • International PHP Conference • 11 Oct 2010

Hi, I’m Ben.
‣ VP of Engineering at Moontoast

‣ Co-founder and organizer emeritus of the Atlanta PHP user group

‣ Current organizer of the Nashville PHP user group

‣ I blog at benramsey.com

‣ I tweet at @ramsey

‣ Please rate this presentation: http://joind.in/2185

Introduction to AtomPub Web Services • Ben Ramsey 2

Atom: RFC 4287


Atom is an XML-based document format that
describes lists of related information known as
“feeds”. Feeds are composed of a number of items,
known as “entries”, each with an extensible set of
attached metadata. For example, each entry has a
title.

The primary use case that Atom addresses is the
syndication of Web content such as weblogs and
news headlines to Web sites as well as directly to
user agents.
—RFC 4287, §1

AtomPub: RFC 5023


The Atom Publishing Protocol is an application-level
protocol for publishing and editing Web Resources using
HTTP and XML 1.0. The protocol supports the creation of
Web Resources and provides facilities for:

Collections: Sets of Resources, which can be retrieved in
whole or in part.

Services: Discovery and description of Collections.

Editing: Creating, editing, and deleting Resources.

The Atom Publishing Protocol is different from many
contemporary protocols in that the server is given wide
latitude in processing requests from clients.

—RFC 5023, §1

AtomPub is a
publishing protocol.

What about RSS?


Content Types
‣ RSS allows only for plain text and escaped HTML content types

‣ Atom provides for plain text, escaped HTML, XHTML, XML, and
Base64-encoded binary data


Internationalization
‣ RSS may have a language set for a feed, but doesn’t have a way to
indicate language for items in the feed

‣ Atom uses the xml:lang attribute to specify language on a per-element
basis

‣ Atom uses IRIs, which allow the usage of characters in identiﬁers
outside of ASCII


Modularity
‣ RSS vocabulary elements aren’t reusable in other XML vocabularies

‣ Atom was designed to allow its vocabulary to be mixed with other XML
vocabularies

‣ Namespaces! Atom has one; RSS does not


Other Things
‣ RSS has no schema; Atom has a RelaxNG schema

‣ RSS deﬁnes no mechanism for handling relative URIs; Atom uses
xml:base

‣ Various implementations in RSS leads to interoperability problems

‣ No standard protocol for publishing; RSS is read only


Atom was created to solve
the RSS problems.

Proﬁle of Atom
‣ Atom Syndication Format

‣ An XML-based web content and metadata syndication format

‣ Deﬁned by IETF RFC 4287

‣ Fixes the “problems” of RSS

‣ XML namespace: http://www.w3.org/2005/Atom


Proﬁle of AtomPub
‣ Atom Publishing Protocol or APP

‣ A protocol for publishing and editing web resources using HTTP and
XML

‣ Deﬁned by IETF RFC 5023

‣ Uses Atom as it’s XML syntax

‣ XML namespace: http://www.w3.org/2007/app


Basics of AtomPub
‣ Each resource has a unique identiﬁer

‣ The resources are well-connected

‣ Resources share the same interface

‣ There is no state; requests are atomic

‣ Follows a resource-oriented architecture


Terminology
‣ Entry

‣ Feed/Collection

‣ Category Document

‣ Service Document


Content Types
‣ Entry:
application/atom+xml;type=entry

‣ Feed/Collection:
application/atom+xml

‣ Category Document:
application/atomcat+xml

‣ Service Document:
application/atomsvc+xml


Designing an AtomPub Service


What will our service do?
‣ Expose users

‣ Expose content

‣ Allow users to manipulate content


Users
‣ /user

‣ /user/{username}

‣ For example: /user/ramsey


Content
‣ /content

‣ /content/{id}

‣ For example: /content/1234


Step 2:
Deﬁne the relationships

Relationship Building
‣ user ⇛ content:
one to many

‣ content ⇛ user:
one to one


Methods Cut & Paste

GET Copy
PUT Paste Over
POST Paste After
DELETE Cut

Actions for User Resources
‣ Retrieve user collection:
GET /user

‣ Create a new user:
POST /user

‣ Modify an existing user:
PUT /user/ramsey

‣ Delete a user:
DELETE /user/ramsey


Actions for Content Resources
‣ Retrieve content:
GET /content

‣ Create new content:
POST /content

‣ Modify content:
PUT /content/1234

‣ Remove content:
DELETE /content/1234


Other Actions
‣ Service discovery:
GET /

‣ Retrieve content for a particular user:
GET /user/ramsey/content


Let’s see it in action


GET / HTTP/1.1
Host: atom.example.org

HTTP/1.x 200 OK
Date: Mon, 21 Sep 2009 16:33:45 GMT
Content-Type: application/atomsvc+xml

<?xml version="1.0" encoding="utf-8"?>
<service xmlns="http://www.w3.org/2007/app"
xmlns:atom="http://www.w3.org/2005/Atom"
xml:base="http://atom.example.org/">
<workspace>
<atom:title>Our Content Store</atom:title>
<collection href="user">
<atom:title>Users</atom:title>
<accept>application/atom+xml;type=entry</accept>
<categories href="cat/user"/>
</collection>
<collection href="content">
<atom:title>Content</atom:title>
<accept>application/atom+xml;type=entry</accept>
<categories href="cat/content"/>
</collection>
</workspace>
</service>

GET /user HTTP/1.1

HTTP/1.x 200 OK
Date: Mon, 21 Sep 2009 16:34:26 GMT
Content-Type: application/atom+xml

<feed xmlns="http://www.w3.org/2005/Atom"
xmlns:app="http://www.w3.org/2007/app"
<title>Users</title>
<updated>2009-09-21T05:21:19Z</updated>
<id>tag:example.org,2009-09:user</id>
<app:collection href="user">
<title>Users</title>
<app:accept>application/atom+xml;type=entry</app:accept>
<app:categories href="cat/user"/>
</app:collection>
<link rel="first" href="user"/>
<link rel="last" href="user?p=23"/>
<link rel="next" href="user?p=2"/>
<entry>
...
</entry>
</feed>

Manipulating a User


GET /user/ramsey HTTP/1.1

HTTP/1.x 200 OK
Date: Mon, 21 Sep 2009 16:34:26 GMT
Content-Type: application/atom+xml;type=entry

<entry xmlns="http://www.w3.org/2005/Atom"
<title>ramsey</title>
<author>
<name>ramsey</name>
</author>
<link rel="self" href="user/ramsey"/>
<link rel="edit" type="application/atom+xml;type=entry"
href="user/ramsey"/>
<link rel="related" href="user/ramsey/content"/>
<id>tag:example.org,2008:user/ramsey</id>
<published>2008-05-23T16:23:34Z</published>
<content type="xhtml">
<div class="vcard">
<a class="fn">Ben Ramsey</a>
<span class="tel">123-456-7890</span>
</div>
</content>
</entry>

Modify the Entry Locally


<title>ramsey</title>
<author>
<name>ramsey</name>
</author>
<link rel="self" href="user/ramsey"/>
<link rel="edit" type="application/atom+xml;type=entry"
href="user/ramsey"/>
<link rel="related" href="user/ramsey/content"/>
<id>tag:example.org,2008:user/ramsey</id>
<content type="xhtml">
<div class="vcard">
<a class="fn url" href="http://benramsey.com/">Ben Ramsey</a>
<span class="org">Moontoast</span>
<span class="tel">123-456-7890</span>
</div>
</content>
</entry>

PUT /user/ramsey HTTP/1.1

{body here}

HTTP/1.x 200 OK
Date: Mon, 22 Sep 2009 09:14:59 GMT

Add Some Content


First, a Few Notes
‣ You need authentication!

‣ Perhaps you need encryption

‣ You deﬁnitely need validation

‣ And I’m not going to tell you how


But I’ll show you the basics.

Get the Categories


GET /cat/content HTTP/1.1

HTTP/1.x 200 OK
Date: Mon, 22 Sep 2009 09:39:26 GMT
Content-Type: application/atomcat+xml

<?xml version="1.0"?>
<app:categories
xmlns:app="http://www.w3.org/2007/app"
xmlns:atom="http://www.w3.org/2005/Atom"
fixed="yes"
scheme="http://atom.example.com/cat/content">
<atom:category term="audio"/>
<atom:category term="video"/>
<atom:category term="game"/>
</app:categories>

Create the Entry Document Locally


<title>Perfect</title>
<author>
<name>Mark Phelps</name>
</author>
<id>tag:example.org,2009:content/perfect</id>
<category term="audio"
scheme="http://atom.example.com/cat/content"/>
<content type="application/mp4">
TWFuIGlzIGRpc3Rpbmd1aXNoZWQsIG5vdCBvbmx5IGJ5IGhpcyByZWF
IHNpbmd1bGFyIHBhc3Npb24gZnJvbSBvdGhlciBhbmltYWxzLCB3aGl
...
</content>
</entry>

POST /content HTTP/1.1

{body here}

HTTP/1.x 202 Accepted
Date: Mon, 22 Sep 2009 09:14:59 GMT

{body contains status indicator}

Authentication?
‣ Atom doesn’t specify a preference

‣ WSSE Username Token

‣ OAuth

‣ Basic authentication

‣ Digest authentication

‣ ???


Oh, yeah.

Where’s the PHP code?

AtomPub in PHP
‣ DOM for reading/writing

‣ SimpleXML for reading

‣ XMLReader for reading

‣ XMLWriter for writing

‣ String concatenation for writing

‣ I recommend XMLReader/XMLWriter; they’re the fastest at parsing and
generating XML


Wrapping Up
‣ You can extend Atom with other XML vocabularies (Dublin Core, etc.)

‣ XML Digital Signature or XML Encryption may be used, or encrypt as a
bag of bits

‣ Use your preferred authentication method

‣ Use HTTP in a RESTful fashion

‣ Use DOM or XMLReader/XMLWriter to parse Atom documents


Questions?
‣ I blog at benramsey.com

‣ I tweet at @ramsey

‣ Please rate this presentation: http://joind.in/2185

‣ Read the Atom speciﬁcations:
RFC 4287
RFC 5023

‣ My company is Moontoast


Introduction to AtomPub Web Services
Copyright © Ben Ramsey. Some rights reserved.

This work is licensed under a Creative Commons
Attribution-Noncommercial-No Derivative Works 3.0
United States License.

For uses not covered under this license, please
contact the author.

Photo Credits
‣ Molecule display, by Christian Guthier

‣ Atom, by jayneandd

‣ Atomium - detail, by Constantin Barbu

‣ Simplicity, by Subterranean Tourist Board

‣ STEREO's Extreme UltraViolet Imager (EUVI), by NASA

‣ Quantum Universe, by Gaurav

‣ Fullerene Nanogears, by NASA

‣ Little Atom, by Marrio

‣ That Atom, by Albert O’Conner

‣ Bokeh Spiral, by Eric Wüstenhagen

‣ Chambered Nautilus Shell - detail, by Jitze Couperus


Introduction to AtomPub Web Services

More Related Content

What's hot (20)

Viewers also liked (8)

Similar to Introduction to AtomPub Web Services (20)

More from Ben Ramsey (9)

Recently uploaded (20)

Introduction to AtomPub Web Services