ROUGH DRAFT

This is VERY rough draft, I plan to restructure but figured it is better to get something rough up than nothing at all. 

Introduction

Hey all,

This page is dedicated to the development of standards/guidelines for RESTful WebHooks. This page should be used to through around ideas about how it aught 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.

Why REST?

WebHooks naturally lends itself to a RESTful design pattern. WebHooks are simple HTTP messages that communicate a change in the state of a web resource. One of the goals of WebHooks is to create a truly programmable web; allowing regular users to connect the various web apps that they interact with in their daily lives. WebHooks is providing a means to publish events to the web and as such should speak the language or the web, RESTful HTTP. The primary weakness of double wrapped envelopes such as SOAP are that they require the consumer to understand both the payload as well as the syntax of the envelope. This creates unnecessary complexity; imagine having to parse a SOAP envelope just to find out that it doesn’t actually contain anything and is just a notification of a change. Does this mean that we must abandon all things complex? Must we avoid XML Schema and service description languages because they are too complex? No, RESTful web hooks should embrace existing tools such as WSDL, WADL, and XML Schema, however, these tools should only be used to enhance the development experience and not as a prerequisite to entry.

Features

So what are the features of RESTful WebHooks? RESTful WebHooks should of course use existing HTTP methods and headers whenever possible. RESTful WebHooks express only four events: ACCESSED, CREATED, UPDATED and DELETED. These events are raised when one of the corresponding HTTP methods are applied to a resource. RESTful messages are implicitly discoverable. RESTful WebHooks support batching through multi-part messages. Here is an example of a RESTful WebHooks Event header:

POST http://www.targeturl.com/mylistener

Content-Type : text/json

Content-Location : http://www.webapp.com/resources/resource/resource-id

X-WebHooks-Url : http://www.webapp.com/resources/web-hooks

X-WebHooks-Event : CREATED

As you can see we use the existing header “Content-Type” to describe the type of the payload, and “Content-Location” to identify the url of the resource that has changed. The custom “X-WebHooks-Url” attribute contains the url to the WebHooks resource. The REST pattern allows us to perform all the operations necessary for WebHooks subscription on a single Url:

Inspect:

HEAD http://www.webapp.com/resource/web-hooks
Accept: text/xhtml
 200 “Ok”
X-WebHooks-Allow: text/json, text/xml, rss/xml, atom/xml
Content-Type : text/xhtml
[XHTML Description ]

When inspecting a web hook

Subscribe:

POST http://www.webapp.com/resource/web-hooks
Content-Type : text/plain
X-WebHooks-Accept : text/json, text/xml
X-WebHooks-Events : POST, DELETE

http://www.targeturl.com/mylistener


 

Unsubscribe:

DELETE http://www.webapp.com/resource/web-hooks



Content-Type : text/plain



X-WebHooks-Events : POST




http://www.targeturl.com/mylistener

Unlike other WebHooks formats, RESTful WebHooks require only a single Url for all subscription tasks. WebHooks are implicitly discoverable, simply add /web-hooks to the url of any web resource to access the WebHooks for that resources. Bots and humans alike can easily determine the “hookability” of a webpage or resource. This mode of discovery allows WebHooks to be sewn directly into the fabric of the web. Eg.