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

Transcription

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

2 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 Please rate this presentation: 2

3 Atom & AtomPub?

4 What s the difference?

5 Atom: RFC

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

7 Atom is an XML language.

8 AtomPub: RFC

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

10 AtomPub is a publishing protocol.

11 What about RSS? 11

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

13 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

14 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

15 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

16 Atom was created to solve the RSS problems.

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

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

19 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

20 Terminology Entry Feed/Collection Category Document Service Document 20

21 Content Types Entry: application/atom+xml;type=entry Feed/Collection: application/atom+xml Category Document: application/atomcat+xml Service Document: application/atomsvc+xml 21

22 Designing an AtomPub Service 22

23 What will our service do? Expose users Expose content Allow users to manipulate content 23

24 Step 1: Define our URIs

25 Users /user /user/{username} For example: /user/ramsey 25

26 Content /content /content/{id} For example: /content/

27 Step 2: Define the relationships

28 Relationship Building user content: one to many content user: one to one 28

29 Step 3: Define the interface

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

31 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

32 Actions for Content Resources Retrieve content: GET /content Create new content: POST /content Modify content: PUT /content/1234 Remove content: DELETE /content/

33 Other Actions Service discovery: GET / Retrieve content for a particular user: GET /user/ramsey/content 33

34 Let s see it in action 34

35 GET / HTTP/1.1 Host: atom.example.org HTTP/1.x 200 OK Date: Mon, 21 Sep :33:45 GMT Content-Type: application/atomsvc+xml

36 <?xml version="1.0" encoding="utf-8"?> <service xmlns=" xmlns:atom=" xml:base=" <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>

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

38 <?xml version="1.0" encoding="utf-8"?> <feed xmlns=" xmlns:app=" xml:base=" <title>users</title> <updated> t05:21:19z</updated> <id>tag:example.org, :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>

39 Manipulating a User 39

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

41 <?xml version="1.0" encoding="utf-8"?> <entry xmlns=" xml:base=" <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> t13:45:00z</updated> <published> t16:23:34z</published> <content type="xhtml"> <div class="vcard" xmlns=" <a class="fn">ben Ramsey</a> <span class="tel"> </span> </div> </content> </entry>

42 Modify the Entry Locally 42

43 <?xml version="1.0" encoding="utf-8"?> <entry xmlns=" xml:base=" <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> t09:14:58z</updated> <published> t16:23:34z</published> <content type="xhtml"> <div class="vcard"> <a class="fn url" href=" Ramsey</a> <span class="org">moontoast</span> <span class="tel"> </span> </div> </content> </entry>

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 :14:59 GMT Content-Type: application/atom+xml;type=entry

45 Add Some Content 45

46 First, a Few Notes You need authentication! Perhaps you need encryption You definitely need validation And I m not going to tell you how 46

47 That s out of scope.

48 :-)

49 But I ll show you the basics.

50 <?xml version="1.0" encoding="utf-8"?> <service xmlns=" xmlns:atom=" xml:base=" <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>

51 Get the Categories 51

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

53 <?xml version="1.0"?> <app:categories xmlns:app=" xmlns:atom=" fixed="yes" scheme=" <atom:category term="audio"/> <atom:category term="video"/> <atom:category term="game"/> </app:categories>

54 Create the Entry Document Locally 54

55 <?xml version="1.0" encoding="utf-8"?> <entry xmlns=" xml:base=" <title>perfect</title> <author> <name>mark Phelps</name> </author> <id>tag:example.org,2009:content/perfect</id> <published> t20:12:08z</published> <category term="audio" scheme=" <content type="application/mp4"> TWFuIGlzIGRpc3Rpbmd1aXNoZWQsIG5vdCBvbmx5IGJ5IGhpcyByZWF IHNpbmd1bGFyIHBhc3Npb24gZnJvbSBvdGhlciBhbmltYWxzLCB3aGl... </content> </entry>

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 :14:59 GMT {body contains status indicator}

57 Authentication? Atom doesn t specify a preference WSSE Username Token OAuth Basic authentication Digest authentication??? 57

58 Did I miss anything?

59 Oh, yeah. Where s the PHP code?

60 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

61 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

62 Questions? I blog at benramsey.com I tweet Please rate this presentation: Read the Atom specifications: RFC 4287 RFC 5023 My company is Moontoast 62

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.

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