Stop Writing REST API Clients

Sigh. This is optimizing for the wrong problem.

Stop creating REST APIs that are only level 1 or 2 (see http://martinfowler.com/articles/richardsonMaturityModel.htm... ).

Start writing HATEOS systems where the client is coupled to the semantic rather than the syntax.

Machine parseable interface descriptions might get rid of some boilerplate but it doesn't make for a more robust client-server relationship.

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

We could give a name to the language we use to define such files. It's a language that defines Web services, so perhaps Web Services Description Language? :-) http://en.wikipedia.org/wiki/Web_Services_Description_Langua...

Flippancy aside, maybe there's a need for a next generation of this that skips all the XML headaches after all.

so, define web services as a json file. JSON-SOAP?