Classifying the CouchDB API

In the context of my Classification of HTTP-based APIs @hanonymity today asked me, how I would classify the CouchDB API.

Ok, let's see. Going to the HTTP Document API immediately reveals that the API definitely violates the hypermedia constraint (see last paragraph) because there is an API documentation in the first place. The only thing one would expect to see for a RESTful API is a set of media type specifications along the lines "The CouchDB API uses the following media types and link relations....which are specified here...".

Next, let's check if the API can be classified as HTTP-based Type II. The fastest way to verify this is usually to look for the use of only specified media types and it is immediately obvious that the CouchDB uses the generic media type application/json and not a specific one that would make the messages self-descriptive. CouchDB API fails the test for HTTP-based Type II, too.

This leaves us with the question whether the API is HTTP-based Type I or if we have to let go all hope because it must be classified as RPC URI-Tunneling. The thing to look out for is of course the use of action names in URIs. It does not take a lot of browsing through the API documentation to reveal that the CouchDB API designers knew what they were doing. The API very thoroughly leverages HTTP mechanics and we can happily conclude that the API is an HTTP-based Type I API.

Is it a problem that the CouchDB API violates two out of four of REST's interface constraints and is therefore not REST at all? I do not think so, because I would not consider achieving loose coupling between a database (backend) and the component that uses the database to be a very useful goal. At least not at the cost that you have to pay on the client side and also because there is strong coupling around the schema anyway between a database and the code that is using it.

However, I think CouchDB API shows quite nicely how an API can still benefit from the simplicity induced by HTTP-based Type I even if we cannot label the API as REST.

A note on the COPY method: It would be helpful to say in the API documentation that the COPY extension method is actually WebDAV's COPY method. And while we are at it, it makes also sense to note that COPY does not really fit HTTP because COPY is a method that works on two resources (Source and Destination) while HTTP does not support such method semantics. For example, caches would not understand that they need to flush the representations of the (now overwritten) destination resource.

This is not a question of RESTfulness though. It would be entirely possible to design an architecture that adheres to the REST style and provides methods that work on two resources.

Service Types Revisited

Working on the RESTifying Procurement show case I realized that it looks as if I had to revisit my approach towards service types. I have argued that a service type is constituted by the set of hypermedia semantics it makes use of. This seemed reasonable since a client developer needs to know at least a minimal set of the possible hypermedia semantics to expect from a service in order to write a client for a service of that kind.

Unfortunately this approach has some problems when services of different kinds use the same set of hypermedia semantics because the differentiating aspect is lost. I realized this because in the procurement example I am basically using a single media type but still have a range of services, for example supplier or carrier.

A possible solution to this issue is to have the all-encompassing media type define the service types. Such types are still necessary to enable lookup based on type, for example in order to find the carrier service of some external business partner. Looking for the procurement service doesn't make that much sense.

Three Aspects of Steady-States

The #rest IRC channel (transcripts here and here) has recently become for me a valuable source for thought stimulation (come and visit). Yesterday we had a discussion regarding steady-states and the following observation has been made:

URIs refer to a certain application state; at least in the sense that one can use a URI to go back to a certain application state or that one can pass a URI to another party to bring this party into that application state.

However, 'that application state' (despite the notion that I can use the URI to get back to it) is not stable over time. The semantics of the mapping are, but the transitions available form that state can change. So, what is the significance of 'that application state'?

I have not figured that out yet, but here is a thought I had this morning as a reaction to the discussion:

A Web application comprises a state machine that can change over time. Each state (aka steady-state) of that state machine has three aspects:

1. Its semantics (what the state means)


2. The serialized state of the associated domain concept (e.g. order 10029)


3. The outgoing transitions to other states

The first of the three is constrained to remain stable over time the other two vary depending on the state of the associated domain concept and the actual state machine the server intends to provide to (that particular) client.

UPDATE: It has come up in a number of places a notion of transient states or ephemeral URIs. As far as I understand the issue circles around the idea of giving distinct URIs to different states of application states. With this approach, an order in some 'review-pending' state would be represented by a different resource (and hence different URI) than the same order in the state 'shipment-initiated'. Please correct me, if I miss the point here.

My response to that can be found in this comment on Ian's blog.

I'd highly apprechiate if someone could shed more light on this issue. I think it is a deep one.

Service Type == Set of Possible Application States

As I have said earlier, in my opinion service types are defined by the set of hypermedia semantics (media types, link relations, ..) they use. Because representations sent by services of a given type are composed of hypermedia semantics from the service type's set it can be said that the service type defines the set of possible representations.

Given that a representation returned by a server corresponds to an application state it follows that a service type defines the set of possible application states.

I like that.

Mac OS X Productivity Apps

Recently I upgraded to Snow Leopard and naturally this made me review what's in my Applications folder. Here are the more interesting products I use more or less regularly:

iWork 09
I love iWork since it came out in 2005 (?). I use Pages a lot for personal stuff because client work usually requires true Office compatibility. I always use Keynote though, never Power Point. Keynote is just great. I prefer Excel over Numbers but mostly because I know it better I guess.

Office 2008
This is a must have on a consultant's machine and I am mostly satisfied with the Mac OS version. Though Word remains as painful as ever. I love Excel - I think it is the best product Microsoft ever made.

Merlin
I am a true lover of this project management application but the occasions where I really need it are rare. I like the look and feel and the millions of export formats. It handles MS Project files nicely.

Nova Mind Platinum
The best mind mapping software ever. The Platinum version includes a script writing feature you can use to prepare presentations in a Beyond Bullet Points way.

Oxygen XML Editor
It took some research to find a nice XML editor for Mac OS X but with Oxygen I found a tool that handles everything you might want to do with XML. I mostly use it for applying XSLTs to some XML and to pretty-print one-line XML files. It is also good for generating example documents from schemas (who understands an XML schema without an example anyway?) and for schema conversions, e.g. RelaxNG to XSD.

Aqua Data Studio
Finding a really good database query tool for Mac OS X was even harder than finding an XML editor. What I wanted was a product that would connect to nearly all common databases and would provide at least the functionality of Toad for serious relational work. Aqua Data Studio is excellent and even has a relational diagramming tool and very sophisticated export and import capabilities. Very good for cycles where you need to work on relational data with a set of Unix tools.

Magic Draw Enterprise
Magic Draw is an excellent UML tools with code and database engineering support and very nice report generation facilities. I mostly use UML for documentation and I love the database reverse engineering feature to extract relational diagrams from database schemas. It is fast and has very nice look and feel for a Java-on-Mac application. But it is unfortunately not a bargain. NoMagic really does maintain and extend the product frequently so paying for the updates has always been worthwhile for me.
Magic Draw has optional plugins for SysML and DoDAF.

Eclipse Classic
Trying to stick to 'standard' Eclipse setup with no plugins except for SVN and the gorgeous vi plugin.

Omni Outliner
The Max OS X classic outliner. Always open to manage my thoughts. N'uff said.

Omni Focus
My current ToDo items application. Though I really want to look at Things.

Screenflow
My favorite tools for creating screen casts. I use this to record code walk-throughs with clients or workshops to have something to hand over afterwards.

Parallels Desktop
Virtual Machine for running Windows if I have to. I used it a couple of years ago to develop on a client's host. So it was: Remote Desktop over VPN over Parallels - worked quite nicely actually. Nowadays of course, Apple's RDT would do the job.

BBEdit
My editor if I really can't use vi or need to convert between encodings.

Quicksilver
Application launcher. Everybody must have Quicksilver, definitely!

Snippet
A little tool for managing code snippets. I often forget about using it, but its a clever thing to have.

UPDATE:

Monkey Office
After looking at a bunch of accounting software products for the Mac, this is the one I picked.

Adobe CS5
It sometimes good to be able to edit designer's work directly, for example to create translations. This saves the roundtrip of having the designer replace the texts. InDesign is an amazing piece of software.

Mondrianum
Yesterday, I learned about Mondrianum. This is a color picker that works together with Adobe's Kuler. Difficult to explain what it does - check out for yourself.

Not worth describing, but there also is EyeTV, Toast, Colloquy, Twitterific, Photoshop, Quicktime Pro, Skype.