Sound advice - blog

Tales from the homeworld

My current feeds

Tue, 2008-Sep-23

Patterns in REST

Central to the REST architectural style is the concept of a uniform interface. The typical elements of the interface are a common set of methods and document types used throughout the architecture to interact with a set of resources.

Lately, I have been preferring to focus on communication patterns rather than methods as elements of the uniform interface. REST patterns are different to Object-Oriented patterns in that they typically do not permit the methods that implement the pattern to change from usage to usage. An Object-Oriented observer pattern would use an implementation-defined subscribe method to register a client's interest, and an implementation-defined call-back method to indicate changes to the client. A publish/subscribe mechanism in REST would use a standard SUBSCRIBE method, and a standard notification method back to the client.

In this way, the constrained set of methods in REST are emergent from the communication patterns in use within the architecture. You have a GET method? Well, you probably have a pattern that makes use of it. Also included in the pattern is all of the valid response codes, reasonable expectations about how redirection and other response codes may be handled, and implicit or explicit mechanisms to recover from a failure.

I see a pattern involving GET requests that allows a client to obtain data from the server in a form the client understands. I see a pattern involving PUT and DELETE requests that allows a client to transfer its changing intent for a piece of server-owned state. I see a pattern for creating a set of server-side resources. I see a pattern involving publish/subscribe for keeping a client up to date with server-side data. I even see borderline REST patterns for reliably queueing or tunnelling sequences of messages to the server.

In REST patterns it is the URLs that change, providing contextual meaning for the interaction. Applying the GET pattern to a particular URL only has meaning if we know that we are checking the state of a lightbulb in order to provide early warning of failure. The PUT pattern only makes sense when we know we are turning the lightbulb on or off. In classical object-orientation this information might be held in the type of the server object. The role of resources in REST moves the emphasis of a pattern from an abstract choreography to a concept more like the use of defined base classes or interface classes.

REST patterns are typically implemented in terms of methods, response codes, and headers. They are agnostic to content and the specific URLs they operate on. They transfer opaque documents according to their mechanics to nominated URL end-points. The set of patterns in a given architecture should be small and well-defined in terms of its intent and its mechanics.

It is generally the client that drives a pattern to its ultimate conclusion. Server code tends to be passive, processing requests as they come in. Understanding the patterns that are present in your architecture will help you produce effective and relevant APIs for client to drive the pattern mechanics. The patterns should help you determine which mechanics should live within the API, and which the application code should be responsible for.

Document your patterns, today!