Introduction to AtomPub Web Services (IPC 2010)

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

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

   View Slide

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

   View Slide

3. Atom & AtomPub?

   

   View Slide

4. What’s the difference?

   

   View Slide

5. Introduction to AtomPub Web Services • Ben Ramsey
   Atom: RFC 4287
   5
   

   View Slide

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

   View Slide

7. Atom is an XML language.
   

   View Slide

8. Introduction to AtomPub Web Services • Ben Ramsey
   AtomPub: RFC 5023
   8
   

   View Slide

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

   View Slide

10. AtomPub is a
    publishing protocol.
    

    View Slide

11. Introduction to AtomPub Web Services • Ben Ramsey
    What about RSS?
    11
    

    View Slide

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

    View Slide

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

    View Slide

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

    View Slide

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

    View Slide

16. Atom was created to solve
    the RSS problems.
    

    View Slide

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

    View Slide

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

    View Slide

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

    View Slide

20. Introduction to AtomPub Web Services • Ben Ramsey
    Terminology
    ‣Entry
    
    ‣Feed/Collection
    
    ‣Category Document
    
    ‣Service Document
    20
    

    View Slide

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

    View Slide

22. Introduction to AtomPub Web Services • Ben Ramsey
    Designing an AtomPub Service
    22
    

    View Slide

23. Introduction to AtomPub Web Services • Ben Ramsey
    What will our service do?
    23
    ‣Expose users
    
    ‣Expose content
    
    ‣Allow users to manipulate content
    

    View Slide

24. Step 1:
    Define our URIs
    

    View Slide

25. Introduction to AtomPub Web Services • Ben Ramsey
    Users
    ‣/user
    
    ‣/user/{username}
    
    ‣For example: /user/ramsey
    25
    

    View Slide

26. Introduction to AtomPub Web Services • Ben Ramsey
    Content
    ‣/content
    
    ‣/content/{id}
    
    ‣For example: /content/1234
    26
    

    View Slide

27. Step 2:
    Define the relationships
    

    View Slide

28. Introduction to AtomPub Web Services • Ben Ramsey
    Relationship Building
    ‣user ⇛ content:

    one to many
    
    ‣content ⇛ user:

    one to one
    28
    

    View Slide

29. Step 3:
    Define the interface
    

    View Slide

30. Methods
    GET
    
    PUT
    
    POST
    
    DELETE
    Cut & Paste
    Copy
    
    Paste Over
    
    Paste After
    
    Cut
    

    View Slide

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

    View Slide

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

    View Slide

33. Introduction to AtomPub Web Services • Ben Ramsey
    Other Actions
    ‣Service discovery:

    GET /
    
    ‣Retrieve content for a particular user:

    GET /user/ramsey/content
    33
    

    View Slide

34. Introduction to AtomPub Web Services • Ben Ramsey
    Let’s see it in action
    34
    

    View Slide

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

    View Slide

36. 
    xmlns:atom="http://www.w3.org/2005/Atom"
    xml:base="http://atom.example.org/">
    
    Our Content Store
    
    Users
    application/atom+xml;type=entry
    
    
    
    Content
    application/atom+xml;type=entry
    
    
    
    
    

    View Slide

37. GET /user HTTP/1.1
    Host: atom.example.org
    HTTP/1.x 200 OK
    Date: Mon, 21 Sep 2009 16:34:26 GMT
    Content-Type: application/atom+xml
    

    View Slide

38. 
    xmlns:app="http://www.w3.org/2007/app"
    xml:base="http://atom.example.org/">
    Users
    2009-09-21T05:21:19Z
    tag:example.org,2009-09:user
    
    Users
    application/atom+xml;type=entry
    
    
    
    
    
    
    ...
    
    
    

    View Slide

39. Introduction to AtomPub Web Services • Ben Ramsey
    Manipulating a User
    39
    

    View Slide

40. GET /user/ramsey HTTP/1.1
    Host: atom.example.org
    HTTP/1.x 200 OK
    Date: Mon, 21 Sep 2009 16:34:26 GMT
    Content-Type: application/atom+xml;type=entry
    

    View Slide

41. 
    xml:base="http://atom.example.org/">
    ramsey
    
    ramsey
    
    
    href="user/ramsey"/>
    
    tag:example.org,2008:user/ramsey
    2009-09-21T13:45:00Z
    2008-05-23T16:23:34Z
    
    
    Ben Ramsey
    123-456-7890
    
    
    
    

    View Slide

42. Introduction to AtomPub Web Services • Ben Ramsey
    Modify the Entry Locally
    42
    

    View Slide

43. 
    xml:base="http://atom.example.org/">
    ramsey
    
    ramsey
    
    
    href="user/ramsey"/>
    
    tag:example.org,2008:user/ramsey
    2009-09-22T09:14:58Z
    2008-05-23T16:23:34Z
    
    
    Ben Ramsey
    Moontoast
    123-456-7890
    
    
    
    

    View Slide

44. PUT /user/ramsey HTTP/1.1
    Host: atom.example.org
    Content-Type: application/atom+xml;type=entry
    {body here}
    HTTP/1.x 200 OK
    Date: Mon, 22 Sep 2009 09:14:59 GMT
    Content-Type: application/atom+xml;type=entry
    

    View Slide

45. Introduction to AtomPub Web Services • Ben Ramsey
    Add Some Content
    45
    

    View Slide

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

    View Slide

47. That’s out of scope.
    

    View Slide

48. :-)
    

    View Slide

49. But I’ll show you the basics.
    

    View Slide

50. 
    xmlns:atom="http://www.w3.org/2005/Atom"
    xml:base="http://atom.example.org/">
    
    Our Content Store
    
    Users
    application/atom+xml;type=entry
    
    
    
    Content
    application/atom+xml;type=entry
    
    
    
    
    

    View Slide

51. Introduction to AtomPub Web Services • Ben Ramsey
    Get the Categories
    51
    

    View Slide

52. GET /cat/content HTTP/1.1
    Host: atom.example.org
    HTTP/1.x 200 OK
    Date: Mon, 22 Sep 2009 09:39:26 GMT
    Content-Type: application/atomcat+xml
    

    View Slide

53. 
    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">
    
    
    
    
    

    View Slide

54. Introduction to AtomPub Web Services • Ben Ramsey
    Create the Entry Document Locally
    54
    

    View Slide

55. 
    xml:base="http://atom.example.org/">
    Perfect
    
    Mark Phelps
    
    tag:example.org,2009:content/perfect
    2009-09-22T20:12:08Z
    scheme="http://atom.example.com/cat/content"/>
    
    TWFuIGlzIGRpc3Rpbmd1aXNoZWQsIG5vdCBvbmx5IGJ5IGhpcyByZWF
    IHNpbmd1bGFyIHBhc3Npb24gZnJvbSBvdGhlciBhbmltYWxzLCB3aGl
    ...
    
    
    

    View Slide

56. POST /content HTTP/1.1
    Host: atom.example.org
    Content-Type: application/atom+xml;type=entry
    {body here}
    HTTP/1.x 202 Accepted
    Date: Mon, 22 Sep 2009 09:14:59 GMT
    {body contains status indicator}
    

    View Slide

57. Introduction to AtomPub Web Services • Ben Ramsey
    Authentication?
    ‣Atom doesn’t specify a preference
    
    ‣WSSE Username Token
    
    ‣OAuth
    
    ‣Basic authentication
    
    ‣Digest authentication
    
    ‣???
    57
    

    View Slide

58. Did I miss anything?
    

    View Slide

59. Oh, yeah.
    Where’s the PHP code?
    

    View Slide

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

    View Slide

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

    View Slide

62. 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 4287

    RFC 5023
    
    ‣My company is Moontoast
    62
    

    View Slide

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

    View Slide

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

    View Slide