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
Host: example.com

    Response:

    HTTP/1.1 200 OK
Link: <...>; rel="post-message",
      <...>; rel="post-batch",
      <http://example.com/topics/mytopic/messages>; 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
Host: example.com

    Response:

    HTTP/1.1 200 OK
Link: <http://example.com/topics/mytopic/messages/111>; rel="create-next"
  3. Client POSTs message to create-next LinkRequest: 
    POST /topics/mytopic/messages/111
Host: example.com
Content-Type: application/json

{'something' : 'abitrary'}

    Response:

    HTTP/1.1 200 Ok
Link: <http://example.com/topics/mytopic/messages/112>; 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.
    Request:

    HEAD /mytopic
Host: example.com

    Response:

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

    POST /mytopic/subscribers
Host: example.com
Content-Type: applicatin/atom+xml

<atom:link rel="post-message-once" href="http://foo.com/messages"/>

    Response:

    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
    Request:

    POST /messages
Host: foo.com

    Response:

    HTTP/1.1 200 OK
Link: <http://foo.com/messages/624>; rel=create-next

    Request:

    POST /messages/624
Host: foo.com
Link: <http://example.com/mytopic/messages/111>; rel=self,
      <http://example.com/mytopic>; rel=generator
Content-Type: whatever

body whateve