couchdb-dev mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From Chris Anderson <>
Subject REST, Hypermedia, and CouchApps
Date Wed, 25 Feb 2009 05:16:10 GMT

Some of you have seen the work that's been going on over at the
CouchApp project. The project started as a thought experiment to see
what can be accomplished using only CouchDB as an app server. It turns
out to raise interesting questions for Couch, especially around REST,
hypermedia, and linking.

Some background: Futon is living proof that CouchDB can host pure Ajax
apps. On the other hand, JSON conforming to CouchDB's HTTP API is not
really RESTful, because a browser can't just pick it up and browse it
(without first loading a JS application that knows how to use the
API). I'm not interested in making Couch RESTful because I want
buzzword compliance, I'm interested because things that are RESTful
tend to win. I want Couch to win.

With _show and _list*, Couch can now host standalone apps that work
just fine without client-side JS. This makes it viable for a whole
additional set of deployment scenarios (like the ones where you want
search engines to index you).

Doing this has taught us some lessons, and motivates some potential
changes to the CouchDB API. I'm not ready to advocate for these
changes (because they are big, as in break-all-existing-clients big)
but I'm fairly certain that there is more REST intelligence on this ML
than there is on the IRC channel at any give time. Maybe together we
can cut the Gordian knot. So let me describe that knot.

== Begin actual technical problem ==

Currently, there is no way for an html attachment to a design document
to link to other resources provided by that design document, absent
client side scripting, or hardcoding the design document name in the
html (neither of which are acceptable).

If you are the HTML hosted at /db/_design/foo/index.html and you want
to provide browsers a link to /db/_view/foo/bar?limit=10 you can't.
You can link to other attachments in the same design document, very

One way to fix this it to give the resources made available by a
design document a common root. This means we can use hrefs like
"_show/docid" to link to a show function from an attachment.  So we
get paths like this:


The downside is that the URLs are longer (and that the change would
break all clients), the upside is the ability to link from one to the
other (and thus be part of the web).

== A related question ==

I checked a patch into Futon the other day (with a note here on dev@)
that links to any apps that are in any of your databases. This is not
meant as an end-user API. It is a step toward an end-user API. The key
similarity is the process for discovering apps. In my mind, an app is
a design document that provides a user interface.

Here's the screenshot of that feature that I linked from my earlier
dev post:

Each app has a start page. Currently, an app's start page is defined
in the design_doc.couchapp.index field. (The details of that field are
subject to change based on the previous section of this mail.) If the
couchapp.index field does not exist, but the design doc has an
index.html attachment, then that is used as its start page. If a
design doc has neither the field nor an index.html attachment, it is
not considered to be an app, and is not linked to from Futon.

The question raised by all of this is how closely do we want CouchDB
to be intertwined with CouchApp?

I've tried to keep the CouchApp project out of the way of CouchDB,
because I'm trying to be humble and not effect CouchDB with this
experiment. Certainly we don't want to give people the impression that
CouchApps are the only way to use CouchDB. I've gone out of my way
whenever possible to make that clear.

OTOH, the CouchApp project is basically designed around CouchDB, to
fit it like a glove. The guiding principle, is that if it can't be
deployed to every unmodified CouchDB server, it's not a CouchApp. As
more people start to develop for CouchDB using CouchApp, things like
the index of available apps become more helpful. The question becomes

Currently listing the available apps takes quite a few HTTP requests
(Futon has to load all the design documents in each DB). If CouchDB
wanted to support CouchApps more directly, it could provide a JSON
resource at /db/_design/ that lists all design docs, along with the
absolute path to their start page, if they have one.

I also want to be clear that there are more ways to write portable,
standalone CouchDB apps than by using the CouchApp project. However,
CouchApp tries to be the simplest thing that could possibly work, for
getting files from your text editor into a design document. So
hopefully it can be a basic helper that people find useful even if
they aren't interested in the higher level helpers we've been adding
to it.

The CouchApp code is released under the Apache 2.0 license, so if
there were community interest in bringing it into the CouchDB project,
it would not be hard.

I'm hoping to gauge the larger CouchDB community interest in
CouchApps. I know some people are mostly interested in Couch as a
giant data store, and would never plan to expose it to end users via
HTTP. Even in that case, a CouchApp would be an ideal way to add
in-house browsing and analytics to a database. The idea of CouchDB
endorsing a particular application framework is a little troubling to
me, which is why I'm trying to limit the points of endorsement to
those which could easily be used by applications which are developed
entirely without the CouchApp helpers.


* we should revisit the _show and _list names before 0.9.

Chris Anderson

View raw message