Revision: 369
Author: monica.keller
Date: Sun Jun 6 11:41:31 2010
Log: Created wiki page through web user interface.
http://code.google.com/p/pubsubhubbub/source/detail?r=369
Added:
/wiki/ArbitraryContentTypes.wiki
=======================================
--- /dev/null
+++ /wiki/ArbitraryContentTypes.wiki Sun Jun 6 11:41:31 2010
@@ -0,0 +1,66 @@
+#summary Proposal for syndicating notifications of changes to arbitrary
resources. Ex: JSON
+#labels JSON
+
+= Introduction =
+The PubSubHubbub protocol works very well for subscribing to get PUSH
updates for Atom or RSS feeds. These formats built on top of XML are easily
extended using namespaces and uniquely identify and timestamp pieces of
content. This proposal allows a consumer to subscribe to any resource that
can be identified with a URL (even if the resource is a jpg) and be
notified of a variety of changes to the resources.
+
+The main use case being targeted is APIs with JSON output but we wanted to
keep this simple and generic so the proposal is content agnostic.
+
+= Details =
+
+== Discovery ==
+
+To make any resource available via PUSH you first need to find at least
one hub to push the changes to and let subscribers know where this hub is
located.
+This will be done using HTTP Headers on the response as described in the
Web Linking http://tools.ietf.org/html/draft-nottingham-http-link-header-10
specification
+
+Example:
+
+HTTP/1.1 200 OK
+
+Content-Type: text/javascript; charset=UTF-8
+
+Date: Sun, 06 Jun 2010 16:15:03 GMT
+
+Content-Length: 268
+
+Link:<http://hub.company.com/>;rel="hub"
+
+Link:<http://hub.organization.org/>;rel="hub"
+
+Additional discovery mechanism can be supported on a Content-Type basis.
For example for application/atom the Link element can still be used to
convey rel="hub".
+
+
+== Anatomy of PuSH Request ==
+When the content changes, just like before, the publisher sends a light
ping to the hub indicating to refetch the resource. The hub verifies the
update request is legitimate by comparing the HTTP response to the previous
one. If the Date header is newer then this is considered an update. The hub
then proceeds to notify all the subscribers copying all the resource
describing HTTP headers which it got from the publisher such as:
+
+ * Content-Type
+ * Content-Length
+ * Date
+ * E-Tag
+
+In addition the POST request will continue to include the X-Hub-Signature
header for the entire message including headers, which subscribers can use
to validate the authenticity and include a new Link rel="self" header which
indicates the resource that changed.
+
+ * Link:<http://my.site.com/page.html>; rel="self"
+
+The subscriber can then use this information to update their data
repository even if updates are syndicated out of order. The unique
identifier is the self URL and the date of the change is conveyed via the
Date header.
+
+== Modeling different resource types ==
+
+A URL can point to a single resource or a list of resources. When it
points to a list as in the case of a feed, the updates sent from the hub to
the publishers are deltas and the subscriber can update their cached copy
by correlating identifiers of items in the list.
+
+If the hub understands the Content-Type and Response Status Codes from the
publisher it can give more details to the subscribers.
+
+The hub can optionally use the methods PATCH, PUT and DELETE to provide
explicit directives of what to do with the content.
+Subscribers which can only support GET or POST requests can support the
X-HTTP-Method-Override.
+
+== Delete Notifications ==
+
+Delete notifications are very drastic and thus we need to make sure they
are intentional. After the light ping, the hub would make a request to the
publisher which would return a 410 Gone instead of a 404 Not Found. See
http://tools.ietf.org/html/rfc2616#section-10.4.11 indicating that the
content needs to be purged. It should also include the Date HTTP header of
when it got deleted in case the requests come out of order to the subscriber
+
+One privacy consideration of this approach is that it does leak the fact
that the content was previously there.
+
+If privacy is a concern the recommended approach is to Authentication
between the publisher and the hub so the hub can "trust" the delete
notifications from the publisher and not need to share publicly this
information. More on the authorization topic will be added to [Pshb_OAuth2]
+
+== Subscription Flow ==
+
+The subscription flow remains the same. One optional enhancement hubs
could provide are content translation services. In that scenario
subscribers would pass the specific Accept header.
