Creating a REST interface for a CQRS application


I recently got caught in a discussion about how to integrate a REST interface with a CQRS based architecture. First of I should mention that I am not a CQRS expert, which is why I will keep the focus on the REST interface part (at least here, everyone's an expert). The origin of the discussion was how to capture user intent despite the limitations of HTTP verbs.

As you know, CQRS defines commands which are used to change the state of the application. The available set of commands can be quite broad, and at first glance, the HTTP verbs POST and PUT, don't quite give the freedom to express intent to the extent that a long set of commands does.

In my mind the root of the problem is that people focus too much on resources in REST. While clearly an important part, REST stands for REpresentational State Transfer. This should make it clear that while a url serves a resource, what you actually get is a representation of that resource. REST is different from "JSON over HTTP" (or "XML over HTTP" for that matter), because the latter returns a serialized data object, whereas REST returns a more rich representation, as we will see.

The first way that REST is richer than JSON over HTTP is that it supports multiple formats (content negotiation, conneg). The other is that REST relies on hypermedia, to guide the user to available actions.

If we leave the data transfer field for a moment and imagine an HTML representation of a resource (a web page), then it seems quite obvious that the page should contain links to other pages, and possibly also a form or two in order to enter some data. When you think about it, links and forms are hypermedia, in that they define where you can go. A form also depends on a URL to send it's data to. As a side note, I think the form tag has become fundamentally misunderstood in the .NET world, because WebForms enclosed the whole page in one form tag, and allowed no other forms on the page.

Once you start to think of a resource as a web page with form elements it becomes easier to understand the idea of resource representations and how this can be used in the JSON format as well (or almost any other format).

In the same way that a web page exposes forms with fields, method definitions and action urls, a JSON representation can contain links to actions which define urls, HTTP verbs and required parameters. A client application can then build up a UI from these action links in the same way that a browser builds up the UI from the HTML representation.

This leads up back to the CQRS part of the application. If you agree with the above description of defining resource representations, then you will agree that the REST service is only a facade over the CQRS application. The CQRS commands can be exposed in the action links of the resources.

While not a requirement for REST, it is generally nice if the links in a resource are active. Again, think of a web page. What do I mean by active? If an order has been cancelled, then the resource representation should not show a link where to cancel the order. In the same way, if certain actions require permissions which the user doesn't have, then don't add the link.

So why is it that people get all wound up about the limited set of verbs in the HTTP protocol? In my opinion it's because they still think in terms of method invocation.

Latest Tweets