RESTful negotiations

Many RESTful applications expose APIs that require the use of components of the URL to specify the output format or the expected mime content-type of the response. This does, however, violate a key REST good practice: the one on URI opacity. There is already an HTTP request header that’s intended for this purpose and it allows multiple mime formats to be specified instead of only one, which is typical of REST APIs that only use the URL.

Examples of using the URI to specify the content-type include, featureserver.org, the Catalog Services specification from the OGC and Feature Demo from the Python, Geospatial, and The Web blog.

If it’s a good practice to NOT use the URI to identify RESTful representation mime-types, then how is a simple client, like the Web Browser suppose to get what it wants? Well, it can’t. Not now, anyway. You’ll have to wait for XHTML 2.0 when links can be specified with proper HTTP request headers such as “ContentType”.

OGC services provide for negotiation via a capabilities request. This request takes the form of a simple HTTP GET on a URL that looks like this: http://myserver.com/service?request=GetCapabilities&... The representation returned is always an XML document that describes a particular service (a resource in REST-speak) and contains the URLs that can be used to perform various operations on that service. This is analogous to using an RSS URL to obtain other URLs: linking to feeds provides further links to stories.

The interesting thing about the capabilities request is that it can be used to negotiate for a particular kind of service. In other words, a client sends a GetCapabilities HTTP request that also includes a description (a RESTful representation) of a desired service they’d prefer to interact with. In response, the service could potentially send back a different set of operation URLs depending on the negotiated service model. Typically though, the GetCapabilities response is implemented as a static XML file sitting on the HTTP server.

Negotiation is a key ingredient for supporting real RESTful applications. Services and specifications up to this point are only half way there, but the future look promising for REST…

Leave a Reply