REST-* Message Draft 5: new post and subcription protocol

I’ve made some small changes to REST-* Message Draft 5.  First is to the reliable posting of messages to a message destination.  The second is to the push model default subscription creation method.

New post-message-once protocol

Previously, the post-message-once link used the POE pattern to avoid duplicate message posting.  I asked around and it seems that the POE pattern isn’t used a lot in practice.  I’m glad because it kinda breaks the uniform interface (unsafe GET) and isn’t really consistent with the other protocols I defined.  It is also very inefficient as you have to make two round trips to post each message.  Nathan Winder, on the reststar-messaging list suggested using a one-off link generated with each message post.  Here’s how it looks:

The post-message-once link URL provided by this link is not used to actually create a message, but rather to obtain a new, one-off, URL. An empty POST should be executed on the post-message-once link. The response provides a new “create-next” link which the client can then post their message to. The link is a “one-off” URL. What that means is that is that if the client re-posts the message to the create-next URL it will receive a 405 error response if the message has already successfully been posted to that URL. If the client receives a successful response or a 405 response, there should be a Link header returned containing a new “create-next” link that the client can post new messages to. Continuously providing a “create-next” link allows the client to avoid making two round-trip requests each and every time it wants to post a message to the destination resource. It is up to the server on whether the create-next URL is a permanent URL for the created message. If it is not permanent, the server should return a Content-Location header to the message.

post-message-once example

  1. Query the destination root resource for links.Request:
    HEAD /topics/mytopic HTTP/1.1


    HTTP/1.1 200 OK
    Link: <...>; rel="post-message",
          <...>; rel="post-batch",
          <>; rel="post-message-once",
          <...>; rel="message-factory"
  2. Client performs a POST request to the post-message-once Link to obtain a create-next link.Request:
    POST /topics/mytopic/messages


    HTTP/1.1 200 OK
    Link: <>; rel="create-next"
  3. Client POSTs message to create-next LinkRequest:
    POST /topics/mytopic/messages/111
    Content-Type: application/json
    {'something' : 'abitrary'}


    HTTP/1.1 200 Ok
    Link: <>; rel="create-next"

Change to push model subscription

I also added a minor change to the push model’s subscriber registration protocol.  In the previous version of the spec, the client would post form parameters to a subscribers URL on the server.  The form parameter would define a URL to forward messages to and whether or not to use the POE protocol to post this message.  I changed this to simple require the client to post an Atom Link.  Since links define protocol semantics, the server can look at the link relationship registered to know how to interact with the subscriber when forwarding messages.  So, if the client registers a post-message-once link when it creates its subscription, the server knows how to interact with the link.  This gives the client and server a lot of simple flexibility in describing how messages should be forwarded.  For example:

This example shows the creation of a subscription and the receiving of a message by the subscriber.

  1. Client consumer queries topic resource for subscribers link.

    HEAD /mytopic


    HTTP/1.1 200 OK
    Link: <, rel=subscribers, type=application/atom+xml
  2. Client does POST-Created-Location pattern to create subscriber

    POST /mytopic/subscribers
    Content-Type: applicatin/atom+xml
    <atom:link rel="post-message-once" href=""/>


    HTTP/1.1 201 Created
    Location: /mytopic/subscribers/333
  3. A message comes in, the message service does a POST to this subscriber based on the interaction pattern described for post-message-once

    POST /messages


    HTTP/1.1 200 OK
    Link: <>; rel=create-next


    POST /messages/624
    Link: <>; rel=self,
          <>; rel=generator
    Content-Type: whatever
    body whateve

2 Responses to REST-* Message Draft 5: new post and subcription protocol

  1. […] REST-* Message Draft 5: new post and subcription protocol […]

  2. […] Web Caching @ E-VAN 01 March 2010 – Video of Mike Amundsen’s talk on HTTP Web Caching. REST-* Message Draft 5: new post and subcription protocol – The latest update to the REST-* Message draft specification. (by Bill Burke) DELETE and 201 […]

Leave a Reply

Fill in your details below or click an icon to log in: Logo

You are commenting using your account. Log Out /  Change )

Google+ photo

You are commenting using your Google+ account. Log Out /  Change )

Twitter picture

You are commenting using your Twitter account. Log Out /  Change )

Facebook photo

You are commenting using your Facebook account. Log Out /  Change )


Connecting to %s

%d bloggers like this: