mca blog

recently i've been seeing quite a bit of talk about "RESTful APIs" and getting annoyed (again). annoyed because these APIs are not at all adhering to the REST constraints but, instead, are merely RPC over HTTP using pre-published URI conventions. Not that there's anything wrong with that. it's gotten so bad that i finally had to run out onto the porch brandishing my shotgun and kick all the kids off my lawn.

luckily, some friends have talked me down off the porch, but i'm still pretty annoyed. so here's my point:

not all Web APIs are the same

there are lots of ways to expose services on the Web. Jan Algermissen (@algermissen) has done some great work in exploring and categorizing Web services in his Classification of HTTP-based APIs posting.

much of this API categorization can be traced to the work of Leonard Richardson and his Maturity Heuristic (2008) . more recently, @MartinFowler posted his Richardson Maturity Model article and this has gotten quite a few more folks interested in the idea of differentiating Web API models. all good stuff.

my ideas on these differences is a bit simpler.

the Web API scale

to my way of thinking there are essentially three basic API models for exposing services on the web:

Classic RPC Tunneling over HTTP

Classic RPC Tunneling is best illustated using XML-RPC or SOAP. the functions are published via single "gateway" URI and usually accessed via HTTP POST with a body describing the details of the call. clients and servers share the interface definition (usually via WSDL, etc.) and any changes to that interface usually must be replicated to all parties.

the key advantage is that Classic RPC limits the number of URIs required to publish a service. the key disadvantage of this approach is that it relies on tight coupling between client and server. both parties must share full knowledge of the function details and any data structures involved and any change to this information can render the service unusable for both parties. Also, Classic RPC over HTTP takes very little advantage of the HTTP protocol or infrastructure since it was not designed to do so.

Modifed RPC over HTTP

Modified RPC elevates the server operations to a set of URIs tied to HTTP protocol methods in a CRUD-based pattern. This is very similar to Classic RPC, but attempts a more direct mapping of the server-side functions to public URIs. clients need to know the URI conventions (and the valid protocol methods for each) in order to access the service and any changes to the URI convention must be replicated to all parties.

the key advantage of this approach is that it makes much better use of the HTTP protocol itself and, in doing so, improves scalability and reliability of the service. the key disadvantage is that Modified RPC suffers the same tight coupling between client and server since the URI convention is a fixed set of knowledge that both parties must share and any changes to this convention (including moving all or part of the service to different server namespaces) can render the service unusable for some or all parties.

Hypermedia Interfaces

Hypermedia Interfaces, like the Classic RPC model, usually publish a single "entry" URI. however, unlike RPC models, this URI is not a gateway for all operations. instead it is a starting point for getting information on how to use the service. in Hypermedia Interfaces, the actual URI collection is unimportant. instead information about the service is shared through an agreed media-type and a defined set of link semantics. the URIs can change (even the starting URI, in some cases) as long as the media-type definition and the link semantics do not.

documenting the service is handled via the media-type definition itself and does not rely on pre-defined URIs or function names. usually media-type definitions do net even rely on protocol details (the same media-type could be used over HTTP, FTP, etc.). this approach is very similar to the one outlined in Chapter 5 of Fielding's dissertation and commonly referred to as REST.

the key advantage of the Hypermedia Interface approach is that there is no coupling of URIs, methods, or function calls between the client and server. this allows the server to modify these details at any time without running the risk of breaking existing clients. the key disadvantage of this approach is that clients and servers must have a full understanding of the link semantics in the shared media-type used to define the service. the work of programming servers as stateless engines based on a media-type is well-established and a common practice. however, programming clients as media-type state engines is not as common and can be deemed too much effort for a certain class of services.

it ain't REST, my friend

boiling it all down, the key point here is that there are very few APIs that are really RESTful. most are really Modified RPC over HTTP. and that's fine. that works for many cases. these APIs do not need to change how they work. but they do need to change how they are named.

and please, rename them. if you don't i might have to grab my shotgun and camp out on the porch for a while.

Note:
for those who want to view a guide on how to see if your API is truely RESTful, check out this detailed list of REST API Rules posted by @fielding in late 2008. and if you think you've got a RESTful API, let me know.