Proposition - RESTful WebHooks : None Resource Payload

[Nathan]

This proposition is part of the RESTful WebHooks Spec located at
http://wiki.webhooks.org/RESTful-WebHooks.

I propose that the payload of a RESTful WebHooks Notification/Event
should never be the resource for which the notification/event was
dispatched. The simple reason for this is that the resource located at
the Content-Location may have changed since the notification was
dispatched. This would mean that the representation of the resource in
the notification would not match the representation at the Content-
Location. REST is stateless and so this is unacceptable.

There are cases where you would rarely want to include the resource in
the payload. For example if a movie is updated it would be
inappropriate to send the movie in the notification payload. Sending
the payload sometimes but not others is inconsistent. One may argue
that the state of the resource at the time of dispatch is critical, if
this is the case then according to RESTful principles this critical
state of the resource should be preserved at a unique URL and so can
be referenced by the Content-Location. Sending the payload with the
notification is wasteful, many of the subscribers may no longer be
actively observing the notification, of those that are many may not
evaluate the payload and instead just log an event occurrence. Caching
the resource would result in improved performance for those that
actually access it.

Nathan

[Daniel Parker]

Sorry to debate with you yet again...

I'm glad you brought up this discussion, but I don't want to be hasty to outlaw ever sending the actual resource contents in a WebHook notification. I would bet that a lot of us can come up with many reasons to sometimes include the resource in the notification, and it may take some time to convince us otherwise. So convince away, the floor is yours... but here are my first oppositions:

The simple reason for this is that the resource located at the Content-Location may have changed since the notification was dispatched. This would mean that the representation of the resource in the notification would not match the representation at the Content-Location. REST is stateless and so this is unacceptable.

IF you think of the notification not as saying "this is what the resource is NOW" but rather "this is what the resource was, at 12:52.25PM March 5, 2010" then you have no quandary. If you want to find out if it's changed since then, you ask for it. If you don't care, you don't. And, if it's changed since then, you probably got another notification anyway. Notifications aren't necessarily covered under the principles of REST (you'll debate that).

Sending the payload sometimes but not others is inconsistent.

I'm not so sure consistency is an issue... if I ask for the updated resource to be included in my hook, it should always be included; or if the hook doesn't include the updated resource, it shouldn't send it. Either way it's doing what I want, whether it's consistent or not.

- - - -

My counter-proposal would be that a WebHook provider always provide the option either to include the updated resource or not to include it. It seems to me that the preference is always going to be on the consumer's side -- not something to be enforced one way or the other by the provider. The most efficient method will probably be that you send the content to those who actually want it (and asked for it when they subscribed), and you don't send the content to those who don't need it (and didn't ask for it when they subscribed). This should be a recommendation to WebHook providers.

- daniel parker -

"You have granted me life and steadfast love, and your care has preserved my spirit." Job 10:12
"The LORD is my chosen portion and my cup . . . indeed, I have a beautiful inheritance." Psalm 16:5-6
"Give what you can ... take nothing back!"

[Ethan Jewett]

This topic is discussed at length in the form of light vs. fat pings
at http://code.google.com/p/pubsubhubbub/wiki/ComparingProtocols It
brings up some important points that are not considered here.

I also don't completely understand the reasons for developing a
separate protocol that feels a lot like PubSubHubBub or RSSCloud.
Wouldn't it make more sense to participate in those protocol
definition process in order to make them more applicable to general
use-cases (currently they are pretty Atom- and RSS-focused,
respectively). Or perhaps a bit more explanations could be added to
the wiki page explaining why a new approach is needed because existing
approaches don't fit the use-case?

Ethan

[Nathan]

> I also don't completely understand the reasons for developing a
> separate protocol that feels a lot like PubSubHubBub or RSSCloud.

> Ethan

I am aware of but have not thoroughly investigated PubSubHubBub. I
know that Jeff, the founder of WebHooks is working with them but has
mentioned that they are not very RESTful. Also, as you mentioned they
focus on syndication as apposed to generic messaging. There is also a
team working on a REST-* Messaging standard, and we should be working
with them as well. However, I think it is important to let these
standards evolve separately for a time, while borrowing ideas from
each other. This way they can be brought back together after each is
fully understood on its own; this ensures that the specific needs of
each group are met in a final solution.

> > Sorry to debate with you yet again...

No problem, one sided discussions rarely yield anything productive.

> IF you think of the notification not as saying "this is what the resource is
> NOW" but rather "this is what the resource was, at 12:52.25PM March 5, 2010"
> then you have no quandary.

Part of defining standards/guidelines is to prevent people from making
mistakes. In simple scenarios like social networking etc. message
integrity is not critical. In enterprise applications it may be. Lets
say a resource is sent in the payload as xml. I try to read the
payload but for whatever reason cannot (corrupted, wrapped in an
unrecognized envelope, or maybe I just need another format like xhtml)
so being a smart developer I fall back to json and issue a request for
the resource in json. Now I have the version from 12:53 PM instead of
12:52 PM and I will *never* be able to access the version at 12:52
again. My server may be offline and I end up getting the version 3
days later, this *could* be a big problem. You may say "well that is
the developers choice," and you are right. But REST is meant to solve
these kinds of problems by being stateless, if the version at 12:52 PM
is important it should be persistent and accessible at any time now or
in the future (within reason). If that developer was told "never send
the resource in the payload and instead make its state persistent" and
he ignored the standard, which he is completely free to do, then if
his data sync gets jacked he is responsible. However, if we do not
issue that warning it is on our hands as we knew of the problem but
chose not to define standards that ensure RESTful data/state
integrity. You may say "well then we should tell the user to make sure
the state is persisted and still allow the payload," also good but
give an inch and they will take a mile. Implementing state as a
resource is unintuitive for most, so chances are if it is not
prohibited (to be standards compliant) it will be ignored, just as we
see very few RESTful services and many REST+RPC hybrids. No one said
the REST made the developers life easier and offered more flexibility
actually everything I have read is to the contrary. REST makes most
things a bit more difficult for the developer but the trade off is
improved scalability, performance, and data integrity. If REST is to
strict for you use REST+RPC or just RPC, if RESTful WebHooks is to
strict for you break some of the guidelines or use another WebHooks
platform.

> Notifications aren't necessarily covered under the principles of REST (you'll debate that).

Yes, I would :)

> The most efficient method will probably be that you send the content to those who
> actually want it (and asked for it when they subscribed)

From a performance standpoint what happens when I stop actively using
that resource but forget to unsubscribe (will happen ALL the time), It
is getting sent to me every time consuming bandwidth for no reason.

I can see only two advantages to sending the Resource in the payload:
1. Client does not have to make an additional request.
2. I don't have to be RESTful and store state changes that are
important. (Why I aughta... This should not event count as a reason)

I see a few obvious reasons why it should not go in the playload:
1. It forces publishers to be RESTful if the resource state is
important ( A GOOD THING, we are defining RESTful standards).
2. Improved performance (caching + less bandwidth)
3. Leaves the payload open for other data such as event info or
subpubhub specific data w/o creating an envelope to allow the
inclusion of the resource (REST no likey Envelopes).
4. Leave content negotiation to the Resource provider, this could be a
big can of worms if subpubhub is expected to handle this (Plugins ==
yuck).
5. Supports a larger async pattern that supports send-and-forget.

[Nathan]

> This topic is discussed at length in the form of light vs. fat pings
> at http://code.google.com/p/pubsubhubbub/wiki/ComparingProtocols It
> brings up some important points that are not considered here.

There were some interesting points there I have to admit. But in this
case "Discussed" is a strong word. I see very little discussion, this
document is PubSubHubBub justifying their use of fat pings. I am
always skeptical of statistics that show that "my" method beats "your"
method at every point. If fat pinging is as superior as is suggested
in this document there would be no need to justify it. And I think the
numbers for syndication are very different from those of WebHooks. A
WebHook is "generally" intended as a tool for moving resources from
one provider to another, possibly transforming them on the way, not as
a tool for broadcasting resources to millions of subscribers.
PubSubHubBub probably cares very little about who receives a message
or whether they receive it successfully and whether the resource state
is represented accurately. They are just shooting messages out, if you
get it good, if you don't that is just fine as well. I am looking to
use WebHooks as an extension to a RESTful "API", data integrity and
deliverability is critical for many of my use cases. And there are
many cases where I never even need to see the resource, I may just be
logging events or perhaps I am simply approving or denying a state
change and can make that decision without accessing the resource.

I am willing to bet that many of these points are completely valid and
that in many ways fat pinging is superior when acting as a content
distribution hub. The major concern that I have is state integrity as
outlined in this and the previous post. Perhaps this topic requires
some compromise. Perhaps we should allow concessions for resource
inclusion. Perhaps two separate messaging modes one for fat pining
messages who's integrity and delivery is non critical and one for
messages that require those insurances. On a side note having the
payload open for other content has a lot of advantages, particularly
when you start viewing it in the context of WebFlow, where I may wan't
to include a standardized event payload that contains links for
actions like denying and approving the PUT command for a resource.

[Nathan]

Perhaps the best policy is to make no assertions about the payload. To
recommend that the resource not be placed in the payload, but not
prohibit it. If WebHooks explicitly states that all data necessary is
stored in the header and that the payload is free to contain anything.
WebHooks extensions such as WebFlow or SubPubHubs are then free to
dictate payload contents.

On Oct 10, 12:24 pm, Nathan <winder.nat...@gmail.com> wrote:
> > This topic is discussed at length in the form of light vs. fat pings

> > athttp://code.google.com/p/pubsubhubbub/wiki/ComparingProtocols It

[Jeff Lindsay]

I like that. I've always been payload neutral.

Regarding these different specs... I think ones with implementations are more likely to succeed. Hence my support of PubSubHubbub. However, I think it was Nathan that pointed out that there are specific needs that can be addressed by slightly different protocols. I think the needs for a specific convention need to be super clear if you're going to support something different.

Also, I know it's hard to get into something so different (since a lot of PubSubHubbub is not terribly relevant to general webhooks -- feeds and such), but I think the best way to attach it's lack of RESTfulness is from within. Meaning, contributing to it or an implementation (code AND spec over just spec, always!) and making incremental changes. Also, just being more actively in the discussion with Brett and Brad in particular is useful.

Anyway, I like the RESTful approach you're working on, but I think it's more likely bits and pieces of it will be used. I would love it if ideas from it were brought into PubSubHubbub for example.

--
Jeff Lindsay
http://webhooks.org -- Make the web more programmable
http://shdh.org -- A party for hackers and thinkers
http://tigdb.com -- Discover indie games
http://progrium.com -- More interesting things

[Nathan]

FYI,
I have a Google doc spec I have been working on for RESTful WebHooks,
in particular the behavior of the SubPubHub. It includes examples of
how PubSubHubbub compares to the RESTful WebHooks.

https://docs.google.com/Doc?docid=0AZoxvcau_qr_ZGNqMjh3OHBfM3QzdnJobmc3&hl=en

> Jeff Lindsayhttp://webhooks.org-- Make the web more programmablehttp://shdh.org-- A party for hackers and thinkershttp://tigdb.com-- Discover indie gameshttp://progrium.com-- More interesting things

[Ethan Jewett]

On Sat, Oct 10, 2009 at 11:47 AM, Nathan <winder...@gmail.com> wrote:
>
> I am aware of but have not thoroughly investigated PubSubHubBub. I
> know that Jeff, the founder of WebHooks is working with them but has
> mentioned that they are not very RESTful. Also, as you mentioned they
> focus on syndication as apposed to generic messaging. There is also a
> team working on a REST-* Messaging standard, and we should be working
> with them as well. However, I think it is important to let these
> standards evolve separately for a time, while borrowing ideas from
> each other. This way they can be brought back together after each is
> fully understood on its own; this ensures that the specific needs of
> each group are met in a final solution.

The page I linked to documentation of one side of an ongoing
discussion occurring on at least a few blogs and mailing lists.

My point is less "stop working on this and get involved in existing
efforts" and more "I don't see a use-case defined or an attempt to
document existing use cases in the protocol discussion and so I'm a
little confused about what this protocol is meant to accomplish".

On the front page of the webhooks wiki (http://webhooks.pbworks.com/)
I see three possible use-cases defined:

1. Push
2. Pipes (in my opinion a special case of Push)
3. Plugin (synchronous Push with a return value)

There is also a list of examples of webhook uses, but not much
discussion in the protocol discussions going on here about documenting
how webhooks are actually used in these existing use-cases. It just
makes it a bit tough to sink my teeth into the discussion.

To give an example, instead of talking theoretically about whether fat
pings or light pings is the right way to go, or if we should be
neutral on the topic, I'd rather talk about how ...

1) A Subscription-based service, PubSubHubBub, has made the decision
to encourage fat pings in order to avoid the "thundering herd" problem
and issue of latency over large deployments.

2) On the other hand, a service like Github may make the decision that
there will be few enough subscribers to a given "hook" and there is a
limited need for instantaneous updates, so they can use a relatively
light ping format (http://github.com/guides/post-receive-hooks),
though I'll point out that they still send a payload.

3) Meanwhile RSSCloud is implemented in such a way that it uses an
extremely light ping format. Why was this decision made for a
subscription service that could suffer from the "thundering herd"
effect. Not sure. But it's worth considering.

This gets a bit more at the real problems that implementors have
considered when making the decision to use light or fat pings, and I'd
argue that considering these decisions makes it more likely that any
protocol developed here will see uptake in the future.

Just a thought from someone who has, admittedly, made little contribution here.

Ethan

[Ethan Jewett]

On Sat, Oct 10, 2009 at 3:56 PM, Nathan <winder...@gmail.com> wrote:
>
> FYI,
> I have a Google doc spec I have been working on for RESTful WebHooks,
> in particular the behavior of the SubPubHub. It includes examples of
> how PubSubHubbub compares to the RESTful WebHooks.
>
> https://docs.google.com/Doc?docid=0AZoxvcau_qr_ZGNqMjh3OHBfM3QzdnJobmc3&hl=en

Our emails crossed on the wire, it seems :-)

I like the comparison to PubSubHubBub. I disagree with the assertion
in the document that having a ping with no payload necessarily
improves performance. There are well documented cases in which this is
not true, depending on your use-case and on what you mean by
performance (CPU cycles of the hub? Number of round-trips? Latency?
Thundering herd?)

Ethan

[Daniel Parker]

My point is less "stop working on this and get involved in existing efforts" and more "I don't see a use-case defined or an attempt to document existing use cases in the protocol discussion and so I'm a little confused about what this protocol is meant to accomplish".

I totally agree with this. I've been thinking, [mostly] Nathan and I have been working on this "RESTful WebHooks" spec, but we don't necessarily have a good definition for the use case(s) or use pattern(s) it is targeting. Some of the debates we've had over various pieces of it have almost for sure been because of this. A spec can't cover all of the different types of uses for WebHooks.

Just a little while ago I wrote up a message about possibly looking at these three "use patterns" -- Push, Pipes and Plugins -- as *the* division of our spec efforts. They seem to generally have their own set of preferences in all the different ways you can implement WebHooks.

Ethan, I think your 3 examples (PubSubHubbub, Github, RSSCloud) and their choices for implementation are a great illustration of this point. PubSubHubbub is mainly focused on Push (subscription, "just let me have the data"), whereas Github is in the Pipes pattern ("I need to digest and do something new with the data"), RSSCloud also in the way of Push... I would imagine light notification could turn out better for many of the Push use cases, but Pipes often need the payload to include the data and Plugins will *always* need it.

Check out my other message on this topic of divisions (starting from the three use patterns when making specs) and reply if you want to be involved in discussions on any one of them.

- daniel parker -

"You have granted me life and steadfast love, and your care has preserved my spirit." Job 10:12
"The LORD is my chosen portion and my cup . . . indeed, I have a beautiful inheritance." Psalm 16:5-6
"Give what you can ... take nothing back!"

[Nathan]

I think what we need to clarify is that WebHooks is not about the
"subscribable web" or the "publishable web", PubSubHubbub seems to be
handling this just fine. WebHooks is about the "programmable web". The
real innovation behind WebHooks is not in taking a blog post and
tuning it into a tweet it is so much more. It is receiving my cable
bill (WebHooks), comparing it to other peoples bills around the
country (WebScripts); then sending me an SMS notifying me that my bill
is ready (WebScripts), waiting for me to respond with approval to pay
the bill (WebHooks). Then going out to a payment gateway and posting
the payment (WebScripts), then receiving notification from the gateway
that the payment was accepted (WebHooks). Them adding the payment to
my pending payments queue in Quicken (WebScripts). This is WebFlow,
allowing the average Joe to program his Web. WebFlow is workflow for
the web.

BTW I have updated my Google Doc, I feel like the RESTful WebHooks
spec is just about there.

> On Sat, Oct 10, 2009 at 5:00 PM, Ethan Jewett <esjew...@gmail.com> wrote:

[Daniel Parker]

Just more on this use cases thing, WebHooks is definitely about subscribing; it's just not only about subscribing. It's entirely about event-notification, event-triggering, message-relaying, subscription, event-logging, and possibly much more.

- daniel parker -