This is a single archived entry from Stefan Tilkov’s blog. For more up-to-date content, check out my author page at INNOQ, which has more information about me and also contains a list of published talks, podcasts, and articles. Or you can check out the full archive.

Governance and REST

Stefan Tilkov,

So, a potential candidate for our SOA consulting team (although we don’t really have anyone who does SOA exclusively) posed an interesting question after finding out that I keep talking about both SOA Governance and REST, but rarely about both of them together: how does the idea of having enforceable, formal contracts (interfaces and policies) that are “governed” within the enterprise fit RESTful HTTP concepts?

A very good question indeed. Here are some thoughts.

First of all, while a RESTful HTTP approach is clearly very different from a “classic” Web services/SOAP-based approach, there is one thing both of them share: they handle data in some format, in many, if not most cases, XML. Of course RESTful HTTP lends itself much easier to using non-XML representations, which is actually great since it means you don’t have to worry about stuffing everything into an XML envelope, even when there’s no point (such as e.g. when you request a PDF or send a JPG, or when a .CSV or .XLS file is exactly what you need). But if you use XML, both variants share exactly the same problem domain — you need to either select standard schemas and formats or define your own, and this requires some sort of governance process.

One of the nice things is that RESTful HTTP is a perfect match for the tools that support this governance — if you make sure that e.g. a namespace name is a resolvable HTTP URI, you get the immediate benefit of having a single source of truth without having to establish a centralized repository if you don’t want to. And even public schemas are integrated very nicely. (In fact, sneaking RESTful HTTP in via the governance tool channel has helped my quite a few times to make client ask “remind me again why we don’t do this for more cases?”).

Although I admit to not having done this in large-scale projects yet, it’s also a very good idea to actually establish a governed and company-wide registry for MIME types, i.e. instead of labeling everything as application/xml, make sure that it’s application/mycompany.order+xml or whatever specific format it is you’re labeling, and store this centrally.

(Update: As Aristotle points out in a comment below: one should stick to the vendor or vanity tree (*/vnd.* and */prs.*, respectively), which means it should be application/vnd.mycompany.order+xml)

So how do you handle the registration of services? In a WS/SOAP architecture, you’d store a whole bunch of XSDs, WSDL files, policies, etc. in a centralized registry. You can do the same in a REST scenario by simply storing the “entry points” (for want of a better term) as links in (X)HTML documents. You have the choice of either using HTML documents (for human users) that link to XML documents (for machine usage), or you can merge the two by using XHTML. To an application, the most common API — UDDI — offers no benefits at all above a plain HTTP interface; in fact, I think it far worse (see this article, authored in by Paul Prescod, for a more detailed discussion).

What do I mean by entry point? One of the key ideas of REST is hypermedia — which leads to the idea of having the possible things you can do with a resource expressed in the representations of this resource, as opposed to out of band. In other words: you don’t actually want to have a description of what a RESTful service (let’s use that as a term for a number of linked resource) does beyond the single link that gets you started; instead, you introduce late binding to whatever you receive included within the representations. Of course nothing at all stops a resource to respond to a specific content type request, e.g. a GET with an Accept header of application/metadata+xml, which might either provide a description or point to something via a link (quite possibly to a document contained in your HTTP-based registry).

I’m not aware of any product specifically tailored to governance of RESTful system. But I don’t believe this to be a severe restriction — after all, the real issues with governance in the WS/SOAP space are not related to tools anyway.

On July 26, 2007 10:51 PM, Aristotle Pagaltzis said:

A minor nit:

make sure that it’s application/mycompany.order+xml

One should stick to the vendor or vanity tree (*/vnd.* and */prs.*, respectively) in those circumstances – so in your example, probably application/vnd.mycompany.order+xml.

Otherwise, right on.

On July 26, 2007 10:56 PM, Aristotle Pagaltzis said:

PS.: citation: RFC 2048.

On July 26, 2007 11:20 PM, Stefan Tilkov said:

Thanks, updated.