Web Service Design with AtomPub

6,055 views
5,982 views

Published on

The Web is transforming into a platform for distributed applications where rich clients connect to web services to retrieve and store data, but these services need a common language. The Atom Publishing Protocol provides is one such language. 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 service for publication and distribution of content.

Published in: Technology
0 Comments
6 Likes
Statistics
Notes
  • Be the first to comment

No Downloads
Views
Total views
6,055
On SlideShare
0
From Embeds
0
Number of Embeds
0
Actions
Shares
0
Downloads
101
Comments
0
Likes
6
Embeds 0
No embeds

No notes for slide

Web Service Design with AtomPub

  1. 1. Web Service Design with AtomPub Ben Ramsey ■ Code Works
  2. 2. Atom & AtomPub?
  3. 3. What’s the difference?
  4. 4. Atom: RFC 4287
  5. 5. Atom is an XML language.
  6. 6. AtomPub: RFC 5023
  7. 7. AtomPub is a publishing protocol.
  8. 8. What about RSS?
  9. 9. 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
  10. 10. 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
  11. 11. 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
  12. 12. 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
  13. 13. Atom was created to solve the RSS problems.
  14. 14. Atom profile ■ 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
  15. 15. AtomPub profile ■ Atom Publishing Protocol ■ 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
  16. 16. AtomPub basics ■ 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
  17. 17. Some terms… ■ Entry ■ Feed/Collection ■ Category Document ■ Service Document
  18. 18. Content types… ■ Entry: application/atom+xml;type=entry ■ Feed/Collection: application/atom+xml ■ Category Document: application/atomcat+xml ■ Service Document: application/atomsvc+xml
  19. 19. Designing an AtomPub service
  20. 20. What will our service do? ■ Expose users ■ Expose content ■ Allow users to manipulate content
  21. 21. 1. Define our URIs
  22. 22. Users ■ /user ■ /user/ramsey
  23. 23. Content ■ /content ■ /content/1234
  24. 24. 2. Define the relationships
  25. 25. ■ user ⇛ content: one to many ■ content ⇛ user: one to one
  26. 26. 3. Define the interface
  27. 27. Methods Cut & Paste GET Copy PUT Paste Over POST Paste After DELETE Cut
  28. 28. ■ Retrieve user collection: GET /user ■ Create a new user: POST /user ■ Modify an existing user: PUT /user/ramsey ■ Delete a user: DELETE /user/ramsey
  29. 29. ■ Retrieve content: GET /content ■ Create new content: POST /content ■ Modify content: PUT /content/1234 ■ Remove content: DELETE /content/1234
  30. 30. ■ Service discovery: GET / ■ Retrieve content for a particular user: GET /user/ramsey/content
  31. 31. Let’s see it in action
  32. 32. 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
  33. 33. <?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>
  34. 34. 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
  35. 35. <?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>
  36. 36. Manipulate a user
  37. 37. 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
  38. 38. <?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>
  39. 39. Modify the entry locally
  40. 40. <?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">Schematic</span> <span class="tel">123-456-7890</span> </div> </content> </entry>
  41. 41. 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
  42. 42. Add some content
  43. 43. First, a few notes ■ You need authentication! ■ Perhaps you need encryption ■ You definitely need validation ■ And I’m not going to tell you how
  44. 44. That’s out of scope.
  45. 45. :-)
  46. 46. But I’ll show you the basics…
  47. 47. <?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>
  48. 48. Get the categories
  49. 49. 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
  50. 50. <?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>
  51. 51. Create the entry document locally
  52. 52. <?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"> TWFuIGlzIGRpc3Rpbmd1aXNoZWQsIG5vdCBvbmx5IGJ5IGhpcyByZWF IHNpbmd1bGFyIHBhc3Npb24gZnJvbSBvdGhlciBhbmltYWxzLCB3aGl ... </content> </entry>
  53. 53. 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}
  54. 54. Authentication? ■ Atom doesn’t specify a preference ■ WSSE Username Token ■ OAuth ■ Basic authentication ■ ???
  55. 55. Did I miss anything?
  56. 56. Oh, yeah. Where’s the PHP code?
  57. 57. ■ Requires lots of parser code; either DOM or XMLReader/XMLWriter ■ No good AtomPub library that I like ■ Apache Abdera is good, but it’s in Java ■ I’m porting it to PHP: http://github.com/ramsey/AbderaPHP
  58. 58. Wrapping up…
  59. 59. ■ 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 auth method ■ Use HTTP in a RESTful fashion ■ Use DOM or XMLReader/XMLWriter to parse Atom documents
  60. 60. Questions? ■ My website is benramsey.com ■ @ramsey on Twitter ■ Rate this talk at joind.in ■ Read the Atom specs at tools.ietf.org/html/rfc4287 tools.ietf.org/html/rfc5023 ■ My company is Schematic schematic.com
  61. 61. Web Service Design with AtomPub 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.

×