introduction to atompub web services
DESCRIPTION
Since 2003, the Atom format has been used as yet another feed format like RSS, but the Atom protocol opens the door to far more uses of Atom as both a means for distribution and publication. Ben Ramsey introduces the Atom format and protocol, explaining how these can form the foundation of any publishing service and serve as a platform for rich Internet applications.TRANSCRIPT
Ben Ramsey • International PHP Conference • 11 Oct 2010Introduction to AtomPub Web Services
Introduction to AtomPub Web Services • Ben Ramsey
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
2
Atom & AtomPub?
What’s the difference?
Introduction to AtomPub Web Services • Ben Ramsey
Atom: RFC 4287
5
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
Atom is an XML language.
Introduction to AtomPub Web Services • Ben Ramsey
AtomPub: RFC 5023
8
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.
Introduction to AtomPub Web Services • Ben Ramsey
What about RSS?
11
Introduction to AtomPub Web Services • Ben Ramsey
Content Types
12
‣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
Introduction to AtomPub Web Services • Ben Ramsey
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 identifiers outside of ASCII
13
Introduction to AtomPub Web Services • Ben Ramsey
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
14
Introduction to AtomPub Web Services • Ben Ramsey
Other Things
‣RSS has no schema; Atom has a RelaxNG schema
‣RSS defines 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
15
Atom was created to solve the RSS problems.
Introduction to AtomPub Web Services • Ben Ramsey
Profile of Atom
‣Atom Syndication Format
‣An XML-based web content and metadata syndication format
‣Defined by IETF RFC 4287
‣Fixes the “problems” of RSS
‣XML namespace: http://www.w3.org/2005/Atom
17
Introduction to AtomPub Web Services • Ben Ramsey
Profile of AtomPub
‣Atom Publishing Protocol or APP
‣A protocol for publishing and editing web resources using HTTP and XML
‣Defined by IETF RFC 5023
‣Uses Atom as it’s XML syntax
‣XML namespace: http://www.w3.org/2007/app
18
Introduction to AtomPub Web Services • Ben Ramsey
Basics of AtomPub
‣Each resource has a unique identifier
‣The resources are well-connected
‣Resources share the same interface
‣There is no state; requests are atomic
‣Follows a resource-oriented architecture
19
Introduction to AtomPub Web Services • Ben Ramsey
Terminology
‣Entry
‣Feed/Collection
‣Category Document
‣Service Document
20
Introduction to AtomPub Web Services • Ben Ramsey
Content Types
‣Entry: application/atom+xml;type=entry
‣Feed/Collection:application/atom+xml
‣Category Document:application/atomcat+xml
‣Service Document:application/atomsvc+xml
21
Introduction to AtomPub Web Services • Ben Ramsey
Designing an AtomPub Service
22
Introduction to AtomPub Web Services • Ben Ramsey
What will our service do?
23
‣Expose users
‣Expose content
‣Allow users to manipulate content
Step 1:Define our URIs
Introduction to AtomPub Web Services • Ben Ramsey
Users
‣ /user
‣ /user/{username}
‣For example: /user/ramsey
25
Introduction to AtomPub Web Services • Ben Ramsey
Content
‣ /content
‣ /content/{id}
‣For example: /content/1234
26
Step 2:Define the relationships
Introduction to AtomPub Web Services • Ben Ramsey
Relationship Building
‣user ⇛ content:one to many
‣content ⇛ user:one to one
28
Step 3:Define the interface
Methods
GETPUTPOSTDELETE
Cut & Paste
CopyPaste OverPaste AfterCut
Introduction to AtomPub Web Services • Ben Ramsey
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
31
Introduction to AtomPub Web Services • Ben Ramsey
Actions for Content Resources
‣Retrieve content:GET /content
‣Create new content:POST /content
‣Modify content:PUT /content/1234
‣Remove content:DELETE /content/1234
32
Introduction to AtomPub Web Services • Ben Ramsey
Other Actions
‣Service discovery:GET /
‣Retrieve content for a particular user:GET /user/ramsey/content
33
Introduction to AtomPub Web Services • Ben Ramsey
Let’s see it in action
34
GET / HTTP/1.1Host: atom.example.org
HTTP/1.x 200 OKDate: Mon, 21 Sep 2009 16:33:45 GMTContent-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.1Host: atom.example.org
HTTP/1.x 200 OKDate: Mon, 21 Sep 2009 16:34:26 GMTContent-Type: application/atom+xml
<?xml version="1.0" encoding="utf-8"?><feed xmlns="http://www.w3.org/2005/Atom" xmlns:app="http://www.w3.org/2007/app" xml:base="http://atom.example.org/"> <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>
Introduction to AtomPub Web Services • Ben Ramsey
Manipulating a User
39
GET /user/ramsey HTTP/1.1Host: atom.example.org
HTTP/1.x 200 OKDate: Mon, 21 Sep 2009 16:34:26 GMTContent-Type: application/atom+xml;type=entry
<?xml version="1.0" encoding="utf-8"?><entry xmlns="http://www.w3.org/2005/Atom" xml:base="http://atom.example.org/"> <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> <updated>2009-09-21T13:45:00Z</updated> <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>
Introduction to AtomPub Web Services • Ben Ramsey
Modify the Entry Locally
42
<?xml version="1.0" encoding="utf-8"?><entry xmlns="http://www.w3.org/2005/Atom" xml:base="http://atom.example.org/"> <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> <updated>2009-09-22T09:14:58Z</updated> <published>2008-05-23T16:23:34Z</published> <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.1Host: atom.example.orgContent-Type: application/atom+xml;type=entry
{body here}
HTTP/1.x 200 OKDate: Mon, 22 Sep 2009 09:14:59 GMTContent-Type: application/atom+xml;type=entry
Introduction to AtomPub Web Services • Ben Ramsey
Add Some Content
45
Introduction to AtomPub Web Services • Ben Ramsey
First, a Few Notes
46
‣You need authentication!
‣Perhaps you need encryption
‣You definitely need validation
‣And I’m not going to tell you how
That’s out of scope.
:-)
But I’ll show you the basics.
<?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>
Introduction to AtomPub Web Services • Ben Ramsey
Get the Categories
51
GET /cat/content HTTP/1.1Host: atom.example.org
HTTP/1.x 200 OKDate: Mon, 22 Sep 2009 09:39:26 GMTContent-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>
Introduction to AtomPub Web Services • Ben Ramsey
Create the Entry Document Locally
54
<?xml version="1.0" encoding="utf-8"?><entry xmlns="http://www.w3.org/2005/Atom" xml:base="http://atom.example.org/"> <title>Perfect</title> <author> <name>Mark Phelps</name> </author> <id>tag:example.org,2009:content/perfect</id> <published>2009-09-22T20:12:08Z</published> <category term="audio" scheme="http://atom.example.com/cat/content"/> <content type="application/mp4">TWFuIGlzIGRpc3Rpbmd1aXNoZWQsIG5vdCBvbmx5IGJ5IGhpcyByZWFIHNpbmd1bGFyIHBhc3Npb24gZnJvbSBvdGhlciBhbmltYWxzLCB3aGl... </content></entry>
POST /content HTTP/1.1Host: atom.example.orgContent-Type: application/atom+xml;type=entry
{body here}
HTTP/1.x 202 AcceptedDate: Mon, 22 Sep 2009 09:14:59 GMT
{body contains status indicator}
Introduction to AtomPub Web Services • Ben Ramsey
Authentication?
‣Atom doesn’t specify a preference
‣WSSE Username Token
‣OAuth
‣Basic authentication
‣Digest authentication
‣???
57
Did I miss anything?
Oh, yeah.
Where’s the PHP code?
Introduction to AtomPub Web Services • Ben Ramsey
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
60
Introduction to AtomPub Web Services • Ben Ramsey
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
61
Introduction to AtomPub Web Services • Ben Ramsey
Questions?
‣ I blog at benramsey.com
‣ I tweet at @ramsey
‣Please rate this presentation: http://joind.in/2185
‣Read the Atom specifications:RFC 4287RFC 5023
‣My company is Moontoast
62
Introduction to AtomPub Web ServicesCopyright © 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.
Introduction to AtomPub Web Services • Ben Ramsey
Photo Credits
64
‣ 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