September 18, 2009

REST Interface Implementation Design

It occurred to me today that there is a subtle design artifact that sits in between the specification of a REST API and its actual implementation. Let me try to explain what I mean:

The specification of a REST API consists of the media types, extensions and link semantics that a potential client must understand to be able to meaningfully interact with the API. The combination of Atom and the Atom Publishing Protocol is a good example of this.

The implementation of a REST API maps the 'back end layer' to a number of resources that provide access to the 'back end layer' in terms of the semantics of the REST API.

This looks like the expected differentiation between interface and implementation, much like you implement an OO interface with a class.

Interestingly, in the case of REST there is a third design artifact that resides somewhere in the middle between interface and implementation: the design decision of what resource are actually exposed and which of the interface semantics are actually used in which circumstances. It could be argued that this decision is part of the implementation, but by distinguishing the two it becomes clearer that there are many potential ways how different systems can manifest a given REST interface.

A class that implements an OO interface will always just implement the methods that constitute the interface, no decisions besides the actual implementation, no surprises. When implementing an Atom Publishing Protocol service, there is an unlimited number of ways to organize feeds and add links to feed or entry documents. One can even build two entirely different APP facades around a given back end but still use the same code to map back end resources (general sense) to feed and entry documents.

When REST API specifications define what resources a client will find on the server side and what type they have then this is an indication that the specification (wrongly) includes the server-side design artifact described above. Such specification elements must be removed from the API to make it RESTful.

No comments:

Post a Comment