mca blog

i've had a number of conversations (both online and off) about URLs, URL construction rules, URI templates, and related items. i've also been doing some research into what Leonard Richardson and i call "description formats" in our new book RESTful Web APIs. these formats are designed to describe services on the Web. they are meant to make it easier for devs working on client implementations to understand how a server works; they describe the server interface. it turns out these service descriptions almost always include URLs, too.

and that's a problem.

constraining server URLs

description formats (like WSDL, WADL, RAML, and others) often include either absolute or relative URLs. these descriptions are telling clients the exact URL for various actions. it seems like a good idea, but its not. why? because these description formats are constraining the URL space for any server that wants to implement that service. IOW, servers don't control their own URLs. there are so many variables in implementing services (operating systems, programming languages, Web frameworks, etc.) that formats which tell servers how the URLs space should be managed can sometimes run afoul of implementation details for that particular server.

and that's a bummer

hold your nose

one of the key properties of the Web is that a client should be able to "follow your nose" to locate new content and actions. IOW, clients should not memorize a set of URLs (or URL construction patterns) and should, instead, be open to discovering new links (ones that weren't there 'yesterday') and following those links (and forms) and activating them when appropriate.

but almost all description formats ignore the "follow your nose" dictum and instead tell clients to "hold their nose" and pre-build all the URLs into source code ahead of time. Essentially, these clients are built to ignore new links and forms. This keeps the client from following new paths provided by the service and basically prevents small changes over time from enriching the Web.

and that's not good.

actions, not addresses

instead of hard-coding URLs, description documents should hard-code the actions that are supported by the service (add, edit, approve, share, etc.) and describe the action details (protocol methods, arguments, etc.) and allow clients to recognize these actions and arguments and use whatever URLs appear at runtime to complete the actions. clients are then able to recognize the same actions used by other servers even when the exact address of these actions are different for each server implementation.

it's the actions that count, not the addresses.

describe the service, not the server

essentially, what most existing description formats do is describe a particular server's implementation, not the service itself. this is fine if your single implementation is so large and popular that hundreds of client devs are happy to create apps just for that single server instance. Twitter, Facebook, Google+, and others are in this group.

but what about all those hundreds of other cool servers out there doing great things on a smaller scale? what about servers like RStatus, Identi.ca, Tout, and others? and what about the 500+ shopping services registered on ProgrammableWeb? is describing each of these implementation separately the only way to go?

the habit of describing each and every server instead of a general description of a service is a wasteful habit we need to break.

there is another way....

Leonard Richardson and i have been working on an alternative approach to describing services. one that does not require constraining a server's URL space. one that describes the service itself, not the implementation of a single server. an approach that focuses on describing the actions, not the addresses. it is very early in the process, but we think ALPS makes it possible to break out of the bad habit of pre-defining URLs and frees client apps to get back to "following their nose" when interacting with a service, no matter where that service lives on the Web.

over the coming weeks, i'll talk more about the emerging ALPS spec and explore the possible ways in which breaking the straight-jacket of URL-based description can increase both the stability and evolvability of services on the Web.

ALPS (or something like it) can help us create better, more powerful service descriptions - and that's a good thing, right?