CoRE Working Group K. Hartke Internet-Draft Universitaet Bremen TZI Intended status: Experimental January 31, 2012 Expires: August 3, 2012 A CoAP REST API for XMPP Publish-Subscribe draft-hartke-core-coap-xmpp-00 Abstract The REST API defined in this document enables Constrained Application Protocol (CoAP) clients to interact with Extensible Messaging Protocol (XMPP) Publish-Subscribe services by delegating the task of creating, retrieving, updating and deleting pubsub items and nodes to a CoAP/XMPP proxy. Status of this Memo This Internet-Draft is submitted in full conformance with the provisions of BCP 78 and BCP 79. Internet-Drafts are working documents of the Internet Engineering Task Force (IETF). Note that other groups may also distribute working documents as Internet-Drafts. The list of current Internet- Drafts is at http://datatracker.ietf.org/drafts/current/. Internet-Drafts are draft documents valid for a maximum of six months and may be updated, replaced, or obsoleted by other documents at any time. It is inappropriate to use Internet-Drafts as reference material or to cite them other than as "work in progress." This Internet-Draft will expire on August 3, 2012. Copyright Notice Copyright (c) 2012 IETF Trust and the persons identified as the document authors. All rights reserved. This document is subject to BCP 78 and the IETF Trust's Legal Provisions Relating to IETF Documents (http://trustee.ietf.org/license-info) in effect on the date of publication of this document. Please review these documents carefully, as they describe your rights and restrictions with respect to this document. Code Components extracted from this document must include Simplified BSD License text as described in Section 4.e of the Trust Legal Provisions and are provided without warranty as described in the Simplified BSD License. Hartke Expires August 3, 2012 [Page 1] Internet-Draft CoAP REST API for XMPP PubSub January 2012 Table of Contents 1. Introduction . . . . . . . . . . . . . . . . . . . . . . . . . 3 2. Protocol and Scheme . . . . . . . . . . . . . . . . . . . . . 3 2.1. Node URI . . . . . . . . . . . . . . . . . . . . . . . . . 4 2.2. Node Meta-Data URI . . . . . . . . . . . . . . . . . . . . 4 2.3. Item URI . . . . . . . . . . . . . . . . . . . . . . . . . 4 3. Link Relation Types . . . . . . . . . . . . . . . . . . . . . 5 4. Media Type Definitions . . . . . . . . . . . . . . . . . . . . 5 4.1. Node Representation . . . . . . . . . . . . . . . . . . . 5 4.2. Meta-Data Representation . . . . . . . . . . . . . . . . . 7 4.3. Item Representation . . . . . . . . . . . . . . . . . . . 7 5. Examples . . . . . . . . . . . . . . . . . . . . . . . . . . . 8 6. Implementation Considerations . . . . . . . . . . . . . . . . 14 7. Security Considerations . . . . . . . . . . . . . . . . . . . 14 8. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 14 9. Acknowledgements . . . . . . . . . . . . . . . . . . . . . . . 14 10. References . . . . . . . . . . . . . . . . . . . . . . . . . . 14 10.1. Normative References . . . . . . . . . . . . . . . . . . . 14 10.2. Informative References . . . . . . . . . . . . . . . . . . 15 Author's Address . . . . . . . . . . . . . . . . . . . . . . . . . 15 Hartke Expires August 3, 2012 [Page 2] Internet-Draft CoAP REST API for XMPP PubSub January 2012 1. Introduction This document defines a REST API that enables Constrained Application Protocol (CoAP) [I-D.ietf-core-coap] clients to interact with Extensible Messaging Protocol (XMPP) [RFC6120] Publish-Subscribe [XEP-0060] services. The task of creating, retrieving, updating and deleting pubsub items and nodes is delegated to a CoAP/XMPP proxy. Publish-Subscribe enables XMPP entities to create nodes at a pubsub service and publish information at those nodes; an event notification (with or without payload) is then broadcasted to all entities that have subscribed to the node. Nodes and published information can be identified by Uniform Resource Identifiers (URIs) [RFC3986] using the 'xmpp.pubsub' URI scheme [XEP-xxxx]. The REST API defined in this document consists of the following elements: o the Constrained Application Protocol (CoAP) [I-D.ietf-core-coap] [I-D.ietf-core-observe]; o the 'xmpp.pubsub' URI scheme [XEP-xxxx]; o the representation formats described in this document; and o the link relation types defined in [RFC5988] and in this document. This document assumes that the reader is familiar with the terms and concepts of [REST], [I-D.ietf-core-coap] and [XEP-0060]. The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", "SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" in this document are to be interpreted as described in [RFC2119]. 2. Protocol and Scheme The Constrained Application Protocol (CoAP) allows clients to specify an arbitrary absolute URI in requests to CoAP proxies. This section defines what it means to perform a CoAP request on an 'xmpp.pubsub' URI, i.e. an URI that identifies a node in the context of a pubsub service or an item in the scope of such a node. If a CoAP request contains a Proxy-URI Option with an 'xmpp.pubsub' URI, then the receiving CoAP end-point (called "the proxy" henceforth) is requested to perform the operation specified by the request method on the indicated pubsub node or item and return the result of the operation to the client. Hartke Expires August 3, 2012 [Page 3] Internet-Draft CoAP REST API for XMPP PubSub January 2012 How the proxy actually satisfies the request is an implementation detail, although the typical case is expected to be the proxy reconstructing the encapsulated XMPP address from the URI, connecting to an appropriate XMPP server, and sending an appropriate XMPP "stanza" (XML fragment) to the XMPP address. Some implementation considerations for this case are outlined in Section 6. 2.1. Node URI For a URI of the form xmpp.pubsub:[// authority/][localpart@]domainpart/[nodeid/], the following methods have the following meaning: GET The GET method requests the proxy to return a current representation of the pubsub node identified by the request URI. POST The POST method requests the proxy to publish the enclosed representation as new pubsub item to the pubsub node identified by the request URI. DELETE The DELETE method requests the proxy to delete the pubsub node identified by the request URI, including all published items within the scope of the node. 2.2. Node Meta-Data URI For a URI of the form xmpp.pubsub:[// authority/][localpart@]domainpart/[nodeid/]?meta-data, the following methods have the following meaning: GET The GET method requests the proxy to return a current representation of the node meta-data identified by the request URI. 2.3. Item URI For a URI of the form xmpp.pubsub:[// authority/][localpart@]domainpart/nodeid/itemid, the following methods have the following meaning: GET The GET method requests the proxy to return a current representation of the pubsub item identified by the request URI. Hartke Expires August 3, 2012 [Page 4] Internet-Draft CoAP REST API for XMPP PubSub January 2012 PUT The PUT method requests the proxy to update or create the pubsub item identified by the request URI with the enclosed representation. DELETE The DELETE method requests the proxy to delete the pubsub item identified by the request URI. 3. Link Relation Types This specification adds the following values to the Link Relation Type registry of [RFC5988]: create Indicates that the link's context is a collection of resources, and refers to a resource that can be used to create new resources within the link's context. update Refers to a resource that can be used to update the link's context. delete Refers to a resource that can be used to delete the link's context. item Refers to a resource in a collection of resources. meta Refers to a resource containing meta-data for the link's context. 4. Media Type Definitions 4.1. Node Representation A node is represented in the CoRE Link Format [I-D.ietf-core-link-format]. The representation SHOULD include, but is not restricted to, the following links: o A link with a relation of "create", if the node supports item publication. o A link with a relation of "delete", if the node can be deleted. o A link with a relation of "meta", if the node has meta-data. o A link with a relation of "last", if the node is a leaf node and has at least one published item. Hartke Expires August 3, 2012 [Page 5] Internet-Draft CoAP REST API for XMPP PubSub January 2012 o A link with a relation of "item" for each published item, if the node is a leaf node. o A link with a relation of "related" for each child node, if the node is a collection node (see [XEP-0163]). Figure 1 shows the representation of an example root node with URI . The representation includes links to all first-level nodes of the pubsub service. ; rel="related"; title="Weblog updates", ; rel="related"; title="News and announcements" Figure 1: Representation of a root node Figure 2 shows the representation of an example collection node with URI . The representation includes links to second-level nodes. <../princely_musings/>; rel="related", <../kingly_ravings/>; rel="related", <../starcrossed_stories/>; rel="related", <../moorish_meanderings/>; rel="related" Figure 2: Representation of a collection node Figure 3 shows the representation of an example leaf node with URI . The representation consists of a link to a resource containing the node's meta-data, a link to a resource containing the last item published to the node, a link to a resource that can be used to publish new items, a link to a resource that can be used to delete the node, and four links to resources containing published items in the context of the node. ; rel="meta", ; rel="last", <>; rel="create", <>; rel="delete", <368866411b877c30064a5f62b917cffe>; rel="item", <3300659945416e274474e469a1f0154c>; rel="item", <4e30f35051b7b8b42abe083742187228>; rel="item", ; rel="item" Figure 3: Representation of a leaf node Hartke Expires August 3, 2012 [Page 6] Internet-Draft CoAP REST API for XMPP PubSub January 2012 4.2. Meta-Data Representation Node meta-data is represented in Turtle [W3C.SUBM-turtle-20110328]. The representation makes statements about a pubsub node using a set predicates derived from the "pubsub#meta-data" FORM_TYPE defined in [XEP-0060]. The predicates are obtained by prefixing each form field name with the string "http://jabber.org/protocol/". For example, the predicate that indicates the name of a node (form field "pubsub# title") is "http://jabber.org/protocol/pubsub#title". Figure 4 shows the representation of example meta-data for the node identified by the URI . @prefix p: . p:type "http://www.w3.org/2005/Atom"; p:creator ; p:creation_date "2003-07-29T22:56Z"; p:title "Princely Musings (Atom)"@en; p:description "Hamlet's Princely Musings weblog."@en; p:language "en"; p:contact ; p:owner ; p:publisher , ; p:num_subscribers 1066 . Figure 4: Representation of meta-data for a node 4.3. Item Representation A pubsub item is represented in an XML-based document format [W3C.REC-xml-20081126] with the following properties: o The document MUST be well-formed. o This specification does not define a DTD, and hence does not require the document to be valid (in the sense used by XML). o For compatibility with XMPP, the document MUST meet the restricted form of XML defined in Section 11.1 of [RFC6120] (i.e., comments, processing instructions, DTD subsets and entity references other than the predefined ones are prohibited). Hartke Expires August 3, 2012 [Page 7] Internet-Draft CoAP REST API for XMPP PubSub January 2012 o The pubsub item is the XML fragment consisting of the document's root element and its content, if any. An example follows. Soliloquy To be, or not to be: that is the question: Whether 'tis nobler in the mind to suffer The slings and arrows of outrageous fortune, Or to take arms against a sea of troubles, And by opposing end them? tag:denmark.lit,2003:entry-32397 2003-12-13T18:30:02Z 2003-12-13T18:30:02Z Figure 5: Representation of an example item 5. Examples This section gives a number of short examples with message flows for CoAP requests with 'xmpp.pubsub' URIs in the Proxy-URI Option. CoAP CoAP/XMPP Client Proxy | | | | +----->| Header: GET (T=CON, Code=1, MID=0x7d40) | GET | Token: 0x75 | | Proxy-URI: "xmpp.pubsub:pubsub.shakespeare.lit/" | | | | |<-----+ Header: 2.05 Content (T=ACK, Code=69, MID=0x7d40) | 2.05 | Token: 0x75 | | | | ; rel="related"; title="Weblog updates", | | ; rel="related"; title="News and announcements" | | Figure 6: Discover first-level nodes Hartke Expires August 3, 2012 [Page 8] Internet-Draft CoAP REST API for XMPP PubSub January 2012 CoAP CoAP/XMPP Client Proxy | | | | +----->| Header: GET (T=CON, Code=1, MID=0x7d41) | GET | Token: 0x76 | | Proxy-URI: "xmpp.pubsub:pubsub.shakespeare.lit/blogs/" | | | | |<-----+ Header: 2.05 Content (T=ACK, Code=69, MID=0x7d41) | 2.05 | Token: 0x76 | | | | <../princely_musings/>; rel="related", | | <../kingly_ravings/>; rel="related", | | <../starcrossed_stories/>; rel="related", | | <../moorish_meanderings/>; rel="related" | | Figure 7: Discover second-level nodes CoAP CoAP/XMPP Client Proxy | | | | +----->| Header: GET (T=CON, Code=1, MID=0x7d42) | GET | Token: 0x77 | | Proxy-URI: "xmpp.pubsub:pubsub.shakespeare.lit/princely_ | | musings/" | | | | |<-----+ Header: 2.05 Content (T=ACK, Code=69, MID=0x7d42) | 2.05 | Token: 0x77 | | | | ; rel="meta", | | ; rel="last", | | <>; rel="create", | | <>; rel="delete", | | <368866411b877c30064a5f62b917cffe>; rel="item", | | <3300659945416e274474e469a1f0154c>; rel="item", | | <4e30f35051b7b8b42abe083742187228>; rel="item", | | ; rel="item" | | Figure 8: Discover Items for a Node Hartke Expires August 3, 2012 [Page 9] Internet-Draft CoAP REST API for XMPP PubSub January 2012 CoAP CoAP/XMPP Client Proxy | | | | +----->| Header: GET (T=CON, Code=1, MID=0x7d43) | GET | Token: 0x78 | | Proxy-URI: "xmpp.pubsub:pubsub.shakespeare.lit/princely_ | | musings/?meta-data" | | | | |<-----+ Header: 2.05 Content (T=ACK, Code=69, MID=0x7d43) | 2.05 | Token: 0x78 | | | | @prefix p: . | | | | | | p:type "http://www.w3.org/2005/Atom"; | | p:creator ; | | p:creation_date "2003-07-29T22:56Z"; | | p:title "Princely Musings (Atom)"@en; | | p:description "Hamlet's Princely Musings weblog."@en; | | p:language "en"; | | p:contact ; | | p:owner ; | | p:publisher , | | ; | | p:num_subscribers 1066 . | | Figure 9: Discover Node Metadata Hartke Expires August 3, 2012 [Page 10] Internet-Draft CoAP REST API for XMPP PubSub January 2012 CoAP CoAP/XMPP Client Proxy | | | | +----->| Header: GET (T=CON, Code=1, MID=0x7d44) | GET | Token: 0x79 | | Proxy-URI: "xmpp.pubsub:pubsub.shakespeare.lit/princely_ | | musings/368866411b877c30064a5f62b917cffe" | | | | |<-----+ Header: 2.05 Content (T=ACK, Code=69, MID=0x7d44) | 2.05 | Token: 0x79 | | | | | | | | The Uses of This World | | | | O, that this too too solid flesh would melt | | Thaw and resolve itself into a dew! | | | | | | tag:denmark.lit,2003:entry-32396 | | 2003-12-12T17:47:23Z | | 2003-12-12T17:47:23Z | | | | Figure 10: Retrieve Item from a Node CoAP CoAP/XMPP Client Proxy | | | | +----->| Header: GET (T=CON, Code=1, MID=0x7d45) | GET | Token: 0x7A | | Observe: 0 | | Proxy-URI: "xmpp.pubsub:pubsub.shakespeare.lit/princely_ | | musings/?last-item" | | | | |<-----+ Header: 2.05 Content (T=ACK, Code=69, MID=0x7d45) | 2.05 | Token: 0x7A | | Observe: 598345 | | | | | | Hartke Expires August 3, 2012 [Page 11] Internet-Draft CoAP REST API for XMPP PubSub January 2012 | | Alone | | | | Now I am alone. | | O, what a rogue and peasant slave am I! | | | | | | tag:denmark.lit,2003:entry-32396 | | 2003-12-13T11:09:53Z | | 2003-12-13T11:09:53Z | | | | | | |<-----+ Header: 2.05 Content (T=CON, Code=69, MID=0xad7d) | 2.05 | Token: 0x7A | | Observe: 598647 | | | | | | | | Soliloquy | | | | To be, or not to be: that is the question: | | Whether 'tis nobler in the mind to suffer | | The slings and arrows of outrageous fortune, | | Or to take arms against a sea of troubles, | | And by opposing end them? | | | | | | tag:denmark.lit,2003:entry-32397 | | 2003-12-13T18:30:02Z | | 2003-12-13T18:30:02Z | | | | | | +- - ->| Header: (T=ACK, Code=0, MID=0xad7d) | | Figure 11: Observing the Most Recent Item Hartke Expires August 3, 2012 [Page 12] Internet-Draft CoAP REST API for XMPP PubSub January 2012 CoAP CoAP/XMPP Client Proxy | | | | +----->| Header: POST (T=CON, Code=2, MID=0x7d46) | PUT | Token: 0x7B | | Proxy-URI: "xmpp.pubsub:pubsub.shakespeare.lit/princely_ | | musings/" | | | | | | | | Soliloquy | | | | To be, or not to be: that is the question: | | Whether 'tis nobler in the mind to suffer | | The slings and arrows of outrageous fortune, | | Or to take arms against a sea of troubles, | | And by opposing end them? | | | | | | tag:denmark.lit,2003:entry-32397 | | 2003-12-13T18:30:02Z | | 2003-12-13T18:30:02Z | | | | | | |<-----+ Header: 2.01 Created (T=ACK, Code=65, MID=0x7d46) | 2.01 | Token: 0x7B | | Figure 12: Publish an Item to a Node CoAP CoAP/XMPP Client Proxy | | | | +----->| Header: DELETE (T=CON, Code=2, MID=0x7d47) |DELETE| Token: 0x7C | | Proxy-URI: "xmpp.pubsub:pubsub.shakespeare.lit/princely_ | | musings/4e30f35051b7b8b42abe083742187228" | | | | |<-----+ Header: 2.02 Deleted (T=ACK, Code=66, MID=0x7d47) | 2.02 | Token: 0x7C | | Hartke Expires August 3, 2012 [Page 13] Internet-Draft CoAP REST API for XMPP PubSub January 2012 Figure 13: Delete an Item from a Node 6. Implementation Considerations (TODO.) 7. Security Considerations (TODO.) 8. IANA Considerations The media type "text/turtle" needs to be assigned a numeric identifier for use with CoAP. 9. Acknowledgements This work was funded by Intel. 10. References 10.1. Normative References [I-D.ietf-core-coap] Shelby, Z., Hartke, K., Bormann, C., and B. Frank, "Constrained Application Protocol (CoAP)", draft-ietf-core-coap-08 (work in progress), October 2011. [I-D.ietf-core-link-format] Shelby, Z., "CoRE Link Format", draft-ietf-core-link-format-11 (work in progress), January 2012. [I-D.ietf-core-observe] Hartke, K. and Z. Shelby, "Observing Resources in CoAP", draft-ietf-core-observe-03 (work in progress), October 2011. [RFC2119] Bradner, S., "Key words for use in RFCs to Indicate Requirement Levels", BCP 14, RFC 2119, March 1997. [RFC3986] Berners-Lee, T., Fielding, R., and L. Masinter, "Uniform Resource Identifier (URI): Generic Syntax", STD 66, Hartke Expires August 3, 2012 [Page 14] Internet-Draft CoAP REST API for XMPP PubSub January 2012 RFC 3986, January 2005. [RFC5988] Nottingham, M., "Web Linking", RFC 5988, October 2010. [W3C.REC-xml-20081126] Sperberg-McQueen, C., Yergeau, F., Maler, E., Paoli, J., and T. Bray, "Extensible Markup Language (XML) 1.0 (Fifth Edition)", World Wide Web Consortium Recommendation REC- xml-20081126, November 2008, . [W3C.SUBM-turtle-20110328] Beckett, D. and T. Berners-Lee, "Turtle - Terse RDF Triple Language", World Wide Web Consortium Team Submission SUBM- turtle-20110328, March 2011, . [XEP-0060] Millard, P., Saint-Andre, P., and R. Meijer, "Publish- Subscribe", XSF XEP 0060, July 2010, . [XEP-xxxx] Hartke, K., "The 'xmpp.pubsub' URI Scheme", XSF XEP xxxx (not yet approved), January 2012, . 10.2. Informative References [REST] Fielding, R., "Architectural Styles and the Design of Network-based Software Architectures", 2000. [RFC6120] Saint-Andre, P., "Extensible Messaging and Presence Protocol (XMPP): Core", RFC 6120, March 2011. [XEP-0163] Saint-Andre, P. and K. Smith, "Personal Eventing Protocol", XSF XEP 0163, July 2010, . Hartke Expires August 3, 2012 [Page 15] Internet-Draft CoAP REST API for XMPP PubSub January 2012 Author's Address Klaus Hartke Universitaet Bremen TZI Postfach 330440 Bremen D-28359 Germany Phone: +49-421-218-63905 Fax: +49-421-218-7000 Email: hartke@tzi.org Hartke Expires August 3, 2012 [Page 16]