Monday, 25 June 2012
HTTP API Complexity
@dret: if your scenario is homogeneous and models are harmonized across participants, #REST is of limited utility for you.
Erik’s tweet just now reminded me of something I’d been wanting to write about for a while; complexity in HTTP APIs, and their effect on how you use the protocol.
One Client, One Server
The simplest HTTP API is one where you have a known client and server talking to each other; they may be managed by separate people or the same team, but regardless, the people developing can communicate about it.
This is often called “integration” by the people doing it, and a ready out-of-band communication channel (whether it be through management, a bug queue, or the pub) means that the server and client can coordinate their actions. HTTP is just a way to get bits on the wire.
As such, the big value for this audience is in reusing existing tools and knowledge; their people know how to deal with HTTP, and their language of choice has a library for it, so they use it. The more sophisticated ones might even use caching.
However, these folks aren’t going to see much value from the more subtle bits of REST, such as HATEOS.
Many Clients, One Server
A very different kind of HTTP API is one where there are many clients. This is common on the Web; consider Twitter’s API, or Google’s, or Amazon’s.
The relationship now is of a single service being consumed by a larger — and likely unknown — group of clients. As such, the service dictates reality, but is also constrained by its past actions, because any incompatible changes will result in — potentially — some broken clients.
Again, REST is providing some latent value here, because there does need to be some de-coupling of the client and server, but there’s still an out-of-band channel for figuring out what’s going on, announcing changes, etc. That's a major escape valve, so they might not see the value of using things like linking to achieve evolveability.
Many Clients, Many Servers
The next level is developing an API that can not only be consumed by many different clients (with their own unique concerns and history), but also deployed by many different servers, using different implementations, and with many possible extensions.
OpenStack’s API has many of these concerns; although it has a single (ish) implementation, it is being deployed in lots of very different ways. Another example is any of the emerging standard cloud APIs (whether they’ll succeed is another blog entry, of course).
Writing this kind of API is hard; your only channel for coordination is the specification itself, and once it’s out in the world, you can only add to it, you can’t take it back. You have to be able to accommodate lots of unforeseen uses, deployment scenarios, extensions, and bad implementation.
These concerns were very similar to the Web when it was set up, and are reflected in HTTP, and therefore REST.
Truth be told, they’re common to most Internet protocols, as designed by the IETF. REST, as embodied in HTTP, just has an advantage in terms of simplicity, tool support, mindshare and capability for many (not all) purposes today.