Artifact Ownership or When Not to Use REST

Here is an indication of situations when applying REST is not appropriate:
When all artifacts that are affected by a possible change are owned by the same project (e.g. stored in the same source code control repository) then REST is not a suitable style.

An example of this is an application that contains a database component for its private use. Usually the database schema is stored in the repository together with the source code. If you face a need to change one, it is easy to change the other (from a developer coordination point of view).

The general take away from this is that artifact ownership can be used as an indicator for how appropriate a candidate style is.

(Consider how much the Unix command line benefits from the uniform API pipe and filter style: Completely decentralized developers can contribute components (grep, awk, sed, less, sort,..) without even engaging into agreeing on how the components talk to each other). The artifacts that make up the unix tool box are maintained by many different parties all over the world.

Generic vs. Specific Media Types and Evolution

Posting moved

GET /stock-quote/foo vs. getStockQuote("foo")

Consider the good old stock quote example from REST vs. RPC discussions. In both variants two kinds of coupling exist.

On the one hand there is the intentional coupling that causes the client to make the call to that particular remote thing and not just any arbitrary one. The intentional coupling is a human choice, manifested in configuration or code.

On the other hand there is technical coupling because the client software needs to know (aka be coupled to) the provided interface. Otherwise the communication would no be able to happen.

Given those two kinds or layers of coupling it makes no sense whatsoever to repeat the specifics already present in the intentional coupling at the technical level by giving that specific remote thing a specific interface.

Once the intentional choice has been made to talk to that remote thing the interface specifics can be factored away.

Why design, implement, test, maintain, document and explain more stuff if you can do the same things with less?

4xx Client Error (But Not It's Fault)

Erik responds to 4xx Client Error. He writes:

"i don't think it appropriate to phrase it like it's the client who necessarily did something wrong when, for example, a 404 is returned. if you follow a URI that was supposed to be persistent and you get a 404 because the server did something wrong, it's quite a stretch to argue that it's your fault. it's pretty clearly not."

I agree that my emphasis on the client doing something wrong wasn't appropriate (but an extreme position is sometimes nice :-). However, I do interpret RFC2616 to be emphasizing that the burden is on the client. While it is obviously not the fault of the client if some resource currently has no representation available (404) I would not agree that "the server did something wrong". The server is free to stop providing representations for a resource and the client just has to account for that to happen.

What is interesting about this is that the conversation between client and server is not considered broken at all because the fact that 4xx errors might occur is part of the contract (and does not indicate a broken contract). This is one of the advantages of a uniform interface with uniform status codes: it can sustain the conversation even when there is a (temporary) gap in expectations.

REST Doesn't Lie

Have been reading about separation of concerns today and came to think that it might be interesting to shift the angle of looking at service evolution: Instead of asking what aspects of services might change it could actually be useful to ask whether there is anything that a service can guarantee not to change, no matter what future requirements it might encounter.

Shifting the point of view revealed a rest constraint that is probably so much taken for granted that it is not talked about very often:

"The only thing that is required to be static for a resource is the semantics of the mapping, since the semantics is what distinguishes one resource from another."

(Section 5.2.2.1 Resources and Resource Identifiers of Roy's dissertation)

This is a guarantee the server has to make that is actually possible to adhere to because no evolution scenario of a server can possibly force it to change that mapping. The other two things that are not subject to change are (obviously) the uniform interface and the use of descriptive message semantics.

Besides these three aspects there is nothing in a networked system that servers can guarantee to clients and REST emphasizes that in an incredibly honest way. The client may depend on the above three aspects to remain true for the entire lifetime of a service but must plan for anything else to change.

What is the take-away? Two things mostly: you are not doing REST unless your system does not adhere to the above and you should exploit the stability of the resource semantics as much as possible in your service design.

Service Descriptions and Legal Contracts

The intermediate result of the thoughts triggered by the recent interchange on the SOA list are here. Comments welcome!

Hidden Contracts and Governance

In a RESTful system the contract between client and server is expressed solely in the form of hypermedia specifications[1]. On the Web this works fine, because there is usually always a human being involved that can act as the ultimate arbiter of semantics when things need to be decided that happen not to be covered by the involved hypermedia specifications.

Examples:

1. When I want to buy a book, what hypermedia is telling me that www.amazon.de is a place to go?

2. When the Amazon site is not reachable, how do I find out where else I could buy a book?

3.How do I know what 'buying a book' means and what the basic sequence of operations is that need to be executed in order to achieve the overall goal?

4. How do I figure out, what the new appropriate sequence of operations is should Amazon significantly change its understanding of the flow of a book purchase?

All of the above are ultimately solved by a human being in the case of the Web and usually don't cause any trouble.

3. is particularly interesting because the fact that no hypermedia specification even touches that question reveals that there is a very high level, common sense contract in operation between human clients and some Web applications.

4. is also interesting because economic sense will usually keep e.g. a book seller from changing the flow of operations in a way that causes the potential buyer to not being able to buy anymore.

How does all this relate to IT governance?

When one applies REST (HTTP that is in practice) in an enterprise IT context, these hidden contracts matter because they either need to be covered by hypermedia specifications (e.g. for the discovery/equivalence examples 1. and 2.) or at least need to be made explicit so they become manageable in an IT governance sense.

Example 3. relates to the general question of how types of services (e.g. 'procurement seller role' or 'repository') can be expressed to provide guidance to client developers regarding the intended sequence of operations.

Example 4 relates to the question of how change can be managed not of the pertaining hypermedia specifications (this is easy!) but of their composition (which is what effectively forms the service type).

Besides being able to frame the problem and ask the questions I do not yet have definitive answers - comments and thoughts are very welcome.

lass="Apple-style-span" style="font-size:medium;">[1] The term 'hypermedia specification' is meant as a general expression for specifications of media types, media type extensions, link relations and 'little' things like category definitions (used for example by Atom and NewsML2).

(Also posted in the XING REST Group)