RESTful WebHooks


RESTful WebHooks (Recomendation) 

 

Introduction

 

Hey all,

This page is dedicated to the development of standards/guidelines for RESTful WebHooks. This page should be used to throw around ideas about how it ought to be done. As these ideas become more structured and coalesce so may this page. I am no Wiki master so if you would like to define a more coherent structure please do. Please post any thoughts you may have in the comments section below, this will serve as a record for the reasoning behind changes in this document. Please avoid making significant changes to this document without first posting suggestions for "pier review." If you want to provide examples of your proposals please link to publicly accessible external documents, lets try to avoid cluttering the comments section with examples.

 

Note: This is still a very rough concept as such you should expect that the recommendations on this page will change. This document is also being maintained on Google Wave, if you have a membership and would like to participate let us know.

 

What are RESTful WebHooks

Briefly, some history and bearings to lay the groundwork for the definition. REST was first "fielded" by Roy Fieldings, in chapter 5 of his doctoral dissertation. See a more readable write-up at RestWiki. REST is, at its core, a sensible way to think about and implement your URIs (the resources - nouns) and HTTP (the interaction with the URIs - verbs). REST reveals that all web sites/applications are web services and the HTTP supports all that is necissary for web services.REST treats a URI as a unique identifier for a resource whether that resource is an image, web page, or complex custom application object.

 

RESTful WebHooks support subscription, notification, and publication through a RESTful interface. This means that HTTP Verbs GET, POST, PUT and DELETE must act on subscription, notification, and publication resources according to REST definitions. RESTful WebHooks MAY overload the POST verb where necessary to support incompatible clients, however, support for native verbs MUST be available. RESTful WebHooks MUST NOT overload the GET verb except where custom idempotent and safe verbs have been defined. RESTful WebHooks MUST support four event types: ACCESSED, CREATED, UPDATED and DELETED. These event types correspond to the four HTTP verbs and notifications should be dispatched when these actions are applied to a resource. If custom HTTP verbs are implemented in your REST design you may add additional event types correlating to the additional verbs (this is generally discouraged). While all HTTP verbs and events must be supported this does not mean that all resources must allow them. You MAY have resources that do not allow the DELETE command, and so a DELETED notification MAY never be dispatched for this resource. Likewise, subscription resources MAY restrict access to verbs such as DELETE.

 

The only restriction on the Body of a request is that data held within the Body of a request MUST NOT contradict WebHooks values in the HEADER of the request; for example, if the HEAD specifies a Notification-Type of UPDATED the Body MUST NOT contradict this type, if it does the type in the HEAD MUST be respected. RESTful WebHooks make allowance for REST+RPC hybrids, the URIs for subscription, publication and notification are not required to be RESTful as long as the HTTP Verbs act on these URIs in the expected manor. While not recommended the Body of a request may also contain un-RESTful data such as SOAP.

 

Subscription, notification and publication entities MUST all be treated as RESTful resources. This means that POSTing to a subscription URI MUST create a subscription resource. DELETEing a subscription resource MUST constitute an un-subscription. While a RESTful WebHooks SubPubHub is not required to permit GET, PUT, or even DELETE these must be the mechanisms through which subscription resources are interacted with. This means you MUST NOT provide this functionality through other means; DELETE MUST be the only mechanism through which to unsubscribe from a subscription.

 

RESTful WebHooks does not define standard formats for subscription, notification, and publication resources or payloads. Resource formats may vary based on the support and features that individual SubPubHubs offer. While standards for these entities are desirable we will omit them from this specification for the sake of flexibility. This will allow implementors of RESTful WebHooks to subscribe to resource and payload standards that best fit their particular use case.

 

Discovery

WebHooks subscription services are discovered by issuing a HEAD request to the resource URI. The URI of the subscription resource MUST be returned in a Link header marked "rel=Subscriptions". The HEAD request MAY return any number of additional headers or body. In this example the Allow header is returned specifying the content negotiation options. The subscription URI SHOULD be constructed in a RESTful manor as subscriptions MUST be treated as RESTful resources.

 

=> HEAD http://www.webapp/resources/resource/abcd

 

<=

200 Ok

Allow : application/json, application/xml

Link : <http://www.webapp.com/resources/resource/abcd/web-hooks>, rel="Subscriptions"

 

Subscription

To subscribe to a WebHook you MUST POST the subscription data as well as the desired Notification-Type to the subscription URI. The response MUST contain the location of the subscription resources as well as a Link to the Subscriptions resource. The body of the subscription POST in this example is a simple URI, RESTful WebHooks make no assertions involving payload content however the Body of the POST command should usually contain subscription data from which a new subscription resource is created. This means the Body could contain hub specific subscription data, allowing WebHooks to be published by SubPubHub hosts with a variety of subscription options.

 

Proprietary Hub Subscription (Inlined)

=>

POST http://www.webapp.com/resources/resource/abcd/web-hooks

Content-Type : text/uri-list

Notification-Type : UPDATED

 

http://www.webscripts.com/myaccount/mylistener

 

<=

201 Created

Location : http://www.webapp.com/resources/resource/abcd/web-hooks/web-hook/1234

Link : <http://www.webapp.com/resources/resource/abcd/web-hooks>, rel="Subscriptions"

 

Public Hub Subscription

=>

POST http://www.subpubhub.com/myaccount/www.webapp.com/resources/resource/abcd/web-hooks

Content-Type : text/uri-list

Notification-Type : UPDATED

 

http://www.webscripts.com/myaccount/mylistener

 

<=

201 Created

Location : http://www.subpubhub.com/myaccount/www.webapp.com/resources/resource/abcd/web-hooks/web-hook/1234

Link : <http://www.subpubhub.com/myaccount/www.webapp.com/resources/resource/abcd/web-hooks>, rel="Subscriptions"

Link : <http://www.webapp.com/resources/resource/abcd>, rev="Resource"

 

PubSubHubbub Subscription (Response Not RESTful)

=>

POST http://myhub.example.com/

Content-Type : application/x-www-form-urlencoded

Notification-Type : UPDATED

 

hub.callback=http://www.webscripts.com/myaccount/mylistener

&hub.mode=subscribe

&hub.topic=http://www.syndicate.com/topic

&hub.verify=sync

 

<=

204 No Content

 

Publication

In order to publish a notification to a SubPubHub the publisher MUST POST notification data to the WebHooks notification queue for the target resource. The publisher MUST include a Link to the Resource that has been acted upon as well as a Notification-Type. The publisher can optionally include an ACKnowledgment Link to which the SubPubHub will post acknowledgements. The body of the post may contain content, WebHooks is payload agnostic and so any custom notification resource may be posted. The SubHubPub MUST return the Location of the newly created notification resource. This notification resource can be queried for statistics involving notification status. The notification can also be deleted preventing any unsent messages from being sent. In the first example a simple custom notification json object is passed setting the number of retires for this notification.

 

Resource Publishes Notification to SubPubHub

=>

POST http://www.webapp.com/resources/resouce/abcd/web-hooks/notifications

Content-Type : application/json

Notification-Type : UPDATED

Link : <http://www.webapp.com/resources/resource/abcd>, rel="Resource"

 

{ retries : 10 }

 

<=

201 Created

Location : http://www.webapp.com/resources/resouce/abcd/web-hooks/notifications/notification/1324

 

 

Resource Publishes Notification to PubSubHubbub (Response Not RESTful)

=>

POST http://myhub.example.com/

Content-Type : application/x-www-form-urlencoded

Notification-Type : UPDATED

Link : <http://www.syndicate.com/topic>, rel="Resource"

 

hub.mode=publish

&hub.url=http://www.syndicate.com/topic

 

<=

204 No Content

 

 

A RESTful SubPubHub MUST distribute messages to the subscribers passing any custom headers to the subscriber. The SubPubHub MAY attach additional headers for the various Links of interest. The SubPubHub MAY also attach a ACKnowledgemnt Link which can forward responses to the Link supplied by the notifier (if any). The SubPubHub SHOULD not include the resource in the payload; the subscriber uses the Resource Link to access the resource, this improves performance, ensures resource integrity, and prevents the PubSubHub from having to manage content negotiation. WebHooks is payload agnostic allowing the SubPubHub to include any hub specific payload for the publication, this means the SubPubHub MAY include the resource if so desired.

 

SubPubHub Distributes Message to Subscribers

=>

POST http://www.webscripts.com/myaccount/mylistener

Notification-Type : UPDATED

Link : <http://www.webapp.com/resources/resource/abcd>, rel="Resource"

Link : <http://www.webapp.com/resources/resource/abcd/web-hooks>, rel="Subscriptions"

Link : <http://www.webapp.com/resources/resource/abcd/web-hooks/web-hook/1234>, rel="Subscription"

Link : <http://www.webapp.com/resources/resource/abcd/web-hooks/notifications/notification/1234/acknowledgments/acknowledgment/1234, rel="ACK"

 

<=

200 Ok

 

Acknowledgement

A notification MAY include an ACKnowledgement Link if acknowledgement is expected. POSTing to the acknowledgement link MAY notify the SubPubHub that the message was received removing it from the notification queue. Acknowledgement MUST be forwarded to the notification source if the ACKnowledgement Link was POSTed as part of notification creation.

 

=>

POST http://www.webapp.com/resources/resource/abcd/web-hooks/notifications/notification/1234/acknowledgments/acknowledgment/1234