This specification describes a mechanism to notify an end-user when a particular web resource changes. For instance a user might want to know when a static web page changes or when a search engine result changes. A web resource might also be something more abstract such as an email mailbox. Then the client would want to know when sub-resources (email messages) are added to the resource. One can also imagine a resource called "the price of stock XYZZY if and only if it is beyond $100." If that resource went from being empty to having a value, then obviously the stock had gone beyond the limit. All of these services can be provided through HTTP. This document describes some conventions to make the construction of generic event client and event server software feasible.
An HTTP Server that wishes to indicate that a particular resource is watchable can do so by returning an "X-Event-Subscription" header to a GET or HEAD request. (Q: is the "X-" a good idea?) This should be a URI. This may be served by the same server but it need not be. It might be implemented by a third-party that polls the Server site or that otherwise knows when the Server changes (e.g. through email notifications).
The Client should POST to the X-Event-Subscription URI. The POST should contain a header called "Event-Target". This is another URI. For interactive applications it would be polite for the server to return an HTML page acknowledging the subscription.
The response to the Subscription MAY include a Location: which is a URI that represents the subscription. If this is DELETEd, the server should cease sending notifications. A future version of this specification may describe the structure of these resources more formally.
When the resource changes, the Server-side Event Source must POST a notification message to the Event-Target URI. The HTTP model is explicitly flexible about what it means for a resource to change. For instance incrementing a page counter might not be considered a meaningful change by a particular Server Application. This specification's definition for "change" will be formally unified with HTTP's at a later date.
A notification message must have the following headers:
The types of Events correspond in semantics to HTTP methods: CHANGED is like PUT over an existing resource, EXTENDED is like POST, DELETED is like DELETE. ADDED is like an "original" PUT. Over time we will come up with guidelines for when it is appropriate to choose user-defined.
The client and server may use content negotiation to determine what should be in the body of the HTTP message. It should in some sense be a representation of the resource, but some form of "difference" may suffice if the two negotiate it.
The the Event-Target URI is a "mailto:" address then the Event Sink may email notifications rather than using HTTP POST. If it is an "ftp:" address then the Event Sink may FTP PUT notifications.
Some legacy applications have trouble working with headers. In the future, this specification may define a convention for using query parameters to represent the same information that is now sent in headers. Ideally, however, query parameters would be reserved for the exclusive use of the application built on top of the notification service.
If these conventions are found to be flexible and general enough, then their basic ideas could be reformulated into an HTTP extension one day.
Consider the example of watching a web page. The client might want a notification if the page changes. This interaction could proceed as follows.
The end-user could type the page's URL into the browser. The server would return an "X-Event-Subscription" URI indicating that it is willing to watch this resource for the client. An HTML HTTP-equiv could also be used if it was more convenient. In addition, the subscription URI could be rendered as an ordinary HTML button. The only problem is that buttons typically cannot set up HTTP headers. This could be done either through Javascript or using the legacy application support described above.
The browser could enable a menu item that would indicate that page is watchable. The user would click the menu item or button. The browser would ask the user whether the user would like the notifications to go to email (mailto: ...) or the current machine (microserver) or a store-and-forward service run by the browser manufacturer (ad-supported). The browser would issue an appropriate POST to the Subscription-URI.
Consider the example of watching a stock quote. The client may only want a notification if it goes below $10.00.
The quote provider could design a web page that generates URIs that match these constraints:
POST http://www.stockquote.com/quotewatcher/PAUL?floor=10.00 Event-Target: http//my.handheld.computer.com/watches?431452
The response could be an HTML page thanking the user for the subscription. Just as on the Web of today, the bit following the question mark can be more or less a query language. If you wanted a notification for every dollar change, you could do "?increment=1.00". If content negotiation is unavailable for some reason, you could also specify the representation you would like.
The client machine would have to have a (potentially tiny) HTTP server running on it. For end-users on devices that are intermittently connected, it would make more sense to set up a server that stores notifications and can deliver them in batch on request (not unlike the role HoTMaiL plays for email).