couchdb-dev mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From "Chris Anderson" <>
Subject _show API (née _form)
Date Fri, 09 Jan 2009 21:39:07 GMT
This is a summary of an IRC discussion prompted by Christopher Lenz
about the "forms" name and API.

The recently introduced _form feature is still rough. On IRC today we
managed to come up with a better name: _show. We like _show because it
makes clear that these functions are for formatting, and that they are
side-effect free, without overloading html's use of the word "form".

The API changes I'm describing haven't been implemented yet, but could
happen soon. The question about the _view show API is a bit more open,
as we don't have an implementation yet. The doc _show API has a subtle
question about whether to use path segments or query params for
function switching.

== The view _show API

The paradigm use case for view forms is generating Atom feeds from
views. By doing this in a CouchDB show function, you'll get row at a
time streaming and low memory overhead, while being able to service
even giant key ranges.

The first question is about user needs. It would be cleaner and easier
to develop a view-show API where each view has only one show function.
Within a function you can still switch on Accept-header (or query
string) so the same function can do both say Atom and RSS feeds.

Is there a strong reason to have more than one show function per view?
I think having more could lead to developer confusion (the inside of a
view show function will be a bit more complex than rereduce even --
head, tail, and row modes), and you can always switch on the query

Assuming the one-form-pre-view constraint, here are some options for
the URL structure:

GET /db/_show_view/mydesign/myview

This would handle the same set of query parameters as the view api, so
you could use startkey, limit, skip etc.

GET /db/_show_view/mydesign/myview?startkey=["foo", "bar"]

Also the full set of query parameters would be available to the show
function so that devs could add eg ?nickname="J Chris A" if they
wanted to render a nickname into the view at runtime (and wreck

== Subtleties in the doc _show API

To run a document through a show function, the URL is:

GET /mydb/_show/mydesign/myshowfunc/docid
GET /mydb/_show/mydesign/othershowfunc/docid

Currently each design doc can have a set of show functions.

If we were to restrict the design doc to a single show function, we'd
have slightly shorter urls:

GET /mydb/_show/mydesign/docid

Should devs need to multiplex on user request, they could use query
string parameters (which are also available in the current
implementation) eg:

GET /mydb/_show/mydesign/docid?specifically=editdoc

so technically the two options have the same capabilities.

I find the current implementation a little easier to think about (it
results in smaller _show functions), and I think the URL length is not
a problem, really. Or rather that the additional length will usually
turn out to be descriptive of its purpose, so it's a net win.

Chris Anderson

View raw message