[pfraze]

We've been experimenting with this at my office. We use yaml descriptions of all of our routes to generate test coverage. We plan to later generate our documentation and client libraries with the same docs.

Document-generated server behavior is something we're researching as well, to possibly represent business logic. We're hoping that patterns can be found and condensed into notations, like Regular Expressions do for string-parsing. We'll post about anything that we come up with.

One of my side projects us an Ajax library which allows javascript to respond to requests (LinkJS [1]). It has a helper object called the Navigator, which is like a miniature Web Agent. It retains a context, and uses the Link header from the response to populate the navigator with relations. It works out like this:

  var nav = Link.navigator('http://mysite.com');
  nav.collection('users').item('pfraze').getJson()
    .then(function(res) {
      console.log(res.body); // => { name:'pfraze', role:'admin' ...}
    })
    .except(function(err) {
      console.log(err.message); // => 404: not found
      console.log(err.response.status); // => 404
    });

The advantage is that the link header is a relatively condensed representation of the resource graph. As a result, it's not a problem to send it and process it every time. You do gain latency, but the internet is only getting faster, and caching can be used. Meanwhile, the server can rewire links without interrupting their clients.

1 https://github.com/pfraze/linkjs