Introduction (Authors: Paul Jones, Ashley Angell, Chris Saad)

Many web resources provide mechanisms for subscribing to changes in their content. However, this change information is only made available via a polling mechanism.

A number of people have proposed mechanisms for subscribing to updates to pages or feeds, however, a missing element of all these proposals is a subscription mechanism. Sadly, this means that every site supporting this feature will likely end up with a different implementation.

Proposal 

Building on top of suggestions and proposals for mechanisms to notify of page changes via Web Hooks and XMPP, GetPingd proposes mechanisms for subscribing to content change notifications in a generic and standardized way.

Design Goals

There are a number of goals for the GetPingd service:

1. Open protocols - any developer should be able to implement any part of the flow: publisher, notifier or consumer.
2. Ease of implementation - the protocol should allow for easy integration with existing technologies.
3. Scalability - similarly to the point on Open protocols, this should be entirely distributed so as to ensure that the entire system is scalable.

Discovery

As GetPingd utilises XRDS for service description, normal XRDS discovery mechanism apply, those being:

• Use of the X-XRDS-Location HTTP header on appropriate documents
• The <meta http-equiv="X-XRDS-Location" content="..." /> tag.

Above these, a series of additional discovery options are proposed in order to allow close integration with formats foreseen to be commonly used with GetPingd:

• Addition of a <link rel="getpingd.updates.descriptor" href="http://example-notifier.getpingd.com/feeds/TheUniversalGadget"> tag to a HTML document header.
• Addition of a similar tag into the head section of an ATOM or RSS document.

Retrieving a GetPingd compatible XRDS document should result in a document looking similar to the following:

<?xml version="1.0"?>
<xrds:XRDS xmlns:xrds="xri://$xrds" xmlns="xri://$xrd*($v*2.0)" ref="http://www.example.com/page" 
    xmlns:getpingd="http://getpingd.com/core/getpingd-1.0" xmlns:getpingd-xmpp="http://getpingd.com/extensions/xmpp/getpingd-1.0">
  <XRD>
    <Service>
      <Type>http://getpingd.com/services/subscribe</Type>
      <URI getpingd:http-method="SUBSCRIBE">http://example-notifier.getpingd.com/feeds/TheUniversalGadget</URI>
      <URI getpingd:http-method="POST">http://example-notifier.getpingd.com/feeds/TheUniversalGadget?method=subscribe</URI>
      <getpingd:Accept type="application/getpingd+http+subscribe+xml>
        <getpingd:SupportsDiff type="application/patch-ops+xml" />
      </getpingd:Accept>
      <getpingd:Accept type="application/getpingd+xmpp+subscribe+xml>
        <getpingd:SupportsDiff type="application/patch-ops+xml" />

        <getpingd-xmpp:PubSub jid="user@example.com" node="feeds/TheUniversalGadget" security="whitelist" />
      </getpingd>
    </Service>
  </XRD>
</xrds:XRDS>

The basic content of this XRD fragment being a description of supported mechanisms for subscribing to the given content.

This document demonstrates a number of details to the client: (Note that the meaning of much of this information is explained later in the document)

1. That the document supports two different urls for change subscription. The client should simply select the first url/method combination that it is also compatible with.
2. The subscribe url supports two types of subscribe requests: application/getpingd+http+subscribe+xml and application/getpingd+xmpp+subscribe+xml (the format of these documents is defined later).
3. These formats have specific details available about them:
   1. Both support the application/patch-ops+xml format for providing diffs.
   2. The XMPP node has a number of XMPP specific configuration options - the location of the XMPP pubsub node to subscribe to, as well as the fact that it uses whitelists for security.

After retrieving this document and selecting the appropriate subscription url and subscription format, the client should generate a subscription request, and send it using the appropriate method to the server. The server will provide a response indicating whether the subscription request was successful.

Subscription Methods

As it would be naive for this proposal to attempt to foresee all of the possible notification methods that may be used, the subscription method instead aims to be extensible as per the mechanisms used in many other IETF RFCs. When a subscribe request body is sent, it should be sent along with a "Content-Type" header. This content type will map to a server accepted type that details a specific subscription mechanism. In order to ensure initial usefulness of GetPingd however, this proposal will detail two notification types: HTTP (Web Hooks) and XMPP.

As noted in the discovery section above, the server will advertise support for various subscription methods via the use of <getpingd:Accept> tags.

HTTP (Web Hook) Notifications

This mechanism utilises the existing "fabric" of the web to deliver notifications, and allows listening services to request notifications by having a given URL invoked. This method is indicated by using the application/getpingd+http+subscribe+xml content type for the subscription body. This method is most likely to be useful when communicating directly between two services with publicly accessible names. For clients that may be behind firewalls, not have persistent names, etc, the XMPP subscription method is far more likely to be appropriate.

 A typical subscription request may look like:

  <subscribe>
    <url href="http://example-listener.getpingd.com/feedupdated?feed=UniversalGadget" method="POST" diff="none" />
  </subscribe>

This request indicates to the notifying server that the consumer would like to be notified at the given url via a POST call, and that no diff should be provided. In the case where a diff may be desired, this should be specified as a content type, similarly to the HTTP PATCH specification:

  <subscribe>
    <url href="http://example-listener.getpingd.com/feedupdated?feed=UniversalGadget" method="NOTIFY" diff="application/patch-ops+xml" />
  </subscribe>

Editorial Note: In later iterations of this specification, it is intended to provide a complete schema for HTTP subscription. However, at this point, due to the potential fluidity of specification, an XSD schema is not yet developed.

XMPP Notifications

XMPP provides a fairly natural fit for change notification. XEP-0060: Publish Subscribe defines methods for subscribing to channels that provide arbitrary information that could easily include document change information. Therefore, GetPingd defines PubSub as a possible transport mechanism, with the intention of providing web-based discovery mechanisms for the node, along with standardised mechanisms for managing subscription white lists.

To subscribe to a XMPP pub sub resource, two details are required: the JID of the publisher and the name of the published node. As shown in the discovery example, it is proposed this information is detailed in a <getpingd-xmpp:PubSub> element.

PubSub describes a number of possibilities for managing the security of channels. The two possibilities of interest to this specification are:

• No Security - subscribes can simply subscribe to the resource
• Whitelist - the producer provides a whitelist of jabber ids that are allowed to subscribe.

The configuration of the resource is advertised in the security attribute of the getpingd-xmpp:PubSub element. The value of this attribute can be either none or whitelist. Based on this value, two subscription paths can be followed:

1. If the security mechanism is none, then the client may simply subscribe to the pubsub resource. No further interaction is required with the HTTP api.
2. If the security mechanism is whitelist, then the client should proceed to form a subscription request and provide that to the server. This request will contain the JID of the consumer that will later be subscribing, and provides the service provider with the opportunity to require authorisation on the web request. (Suggested authorisation mechanisms are discussed later in the proposal).

A whitelist addition request would look like:

  <subscribe>
    <consumer jid="listener@example.com/FeedListener" />
  </subscribe>

Editorial Note: In later iterations of this specification, it is intended to provide a complete schema for XMPP subscription. However, at this point, due to the potential fluidity of specification, an XSD schema is not yet developed.

Interaction with existing notification implementations

Many blogging engines available today support notification mechanisms, primarily for the purposes of notifying search engines that new content is available. Therefore, a suggested implementation of this proposal would result in a service that supports the subscription semantics of this proposal, whilst providing content producers with an appropriate X-XRDS-Location meta tag or getpingd.updates.description link to place in their document metadata. The blog could be reconfigured to ping this service, which would then perform the notifications based on configured subscriptions.

Existing Implimentations

Syncstream