X-DOAP

Danny’s discussion about sending FOAF URLs as HTTP headers reminded me that I’d not yet followed up on some similar proposals I’d made at XTech 2005. In particular, the use of DOAP descriptions instead of “API Keys” for RESTful interfaces.
In my paper after reviewing how services supported authentication and linking of resources, I wrote:

Many of the services support the notion of an “API Key”. These keys are allocated on a per-application basis and are a required parameter in all requests. Typically a form is provided that allows an application developer to quickly obtain a key. Often some context about its intended usage, such as application name, description and a homepage URL must be supplied.

While API keys are not used for authentication they are used as a mechanism to support usage tracking of the API, e.g. to identify active applications and potentially spot abuses. From this perspective they are a useful feature that furnishes service providers with useful usage statistics about client applications…

Later, I critiqued the use of hypermedia to link together different resources exposed via several RESTful interfaces, noting that very few actually used this technique instead relying on the client to construct additional URLs in order to extract more data. One item that frequently needs to be added is an API Key which:

…prohibits free publishing of links, as given URL is only suitable for use by a single application, the one to which the key was assigned.

It is the use of API keys that is the most troublesome. While obviously providing a useful feature, API keys hamper loose ad hoc integration; clients must know how to manipulate a URL to insert an API key. Therefore, while a service may provide unauthenticated use of read-only URLs, these links cannot be openly published without also sharing an API key. This obviously undermines their potential benefits.

An alternative to using API keys in the URL, is to require applications to identify themselves using an existing HTTP feature: the User-Agent header. This header can be used to pass an application name, URL, or other token to a service without requiring modification of the request URL. An API key is actually request metadata, and HTTP headers are the correct place for this metadata to be communicated.

Some APIs already support or encourage use of User-Agent, notably del.icio.us and WebJay. However the technique isn’t that suitable for all environments, e.g. a bookmarklet, where one has no control over the HTTP headers.
User-Agent is also problematic due to its unstructured format: the field is basically free text and browser User-Agent‘s are already hopelessly muddled.
In my presentation I suggested using an alternate HTTP header X-DOAP whose value would be the URI of the DOAP description of the client application. This header would supplant the use of API Keys, or at least encouraged as an alternate mechanism for identifying a client application. To my mind this provides the same level of detail and usage tracking as an API key, but in a more flexible manner.
It’s worth noting that Greasemonkey (and other AJAX environments I assume) allow the addition of custom HTTP headers to outgoing requests. So one can use both X-DOAP and Danny’s (X-)FOAF headers to identify both the client application and the user. As far as I can see it’s only bookmarklets that are limited to not having access to either the User-Agent settings or other outgoing headers. I’m not certain that a lot of API accesses come from those environments anyway, I’d hazard that custom applications and AJAX clients are increasingly the norm.
X-DOAP could be used now, assuming consensus could be reached amongst the various service providers. As Danny has noted an official registration would carry a lot more weight.