couchdb-dev mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From "Matt Goodall" <>
Subject API suggestions
Date Thu, 04 Dec 2008 12:01:49 GMT

OK, I'm not a big user of CouchDB yet (I hope that will change one
day!) but, since you're all talking about heading for 1.0, I thought I
would post some thoughts on the CouchDB API in case any of it makes
sense to users with real experience of using it in applications.

I'm aware that some are significant changes and would break language
bindings but better now than post 1.0!

So, here goes ... I have my flame proof jacket on ... time to post to
the mailing list! ;-)

Hope it makes sense.

- Matt


= Document Revisions =

Identify document revision using a segment arg instead of query param, e.g.


That would make child resources (attachments and whatever might happen
in the future) more easily addressable, e.g.

	GET my_db/my_doc;rev=123/foo.txt

I think the biggest benefit is probably accessing attachments. To me:

	PUT my_db/my_doc;rev=123/foo.txt

is so much prettier, more readable and more "semantically" correct than:

	PUT my_db/my_doc/foo.txt?rev=123

Not sure how important the rev= bit would be; my_db/my_doc;123 may
well be sufficient.

= Document Bits =

(See also, Reserved Names)

It might be nice to move attachments to a special '_attachments' child
of the document resource, e.g. my_db/my_doc/_attachments/foo.txt.

That's consistent with the structure of my_doc's JSON document and
also allows CouchDB to provide more information about the document
should it ever need to. e.g. my_db/my_doc/_views might return a list
of the URLs of views the document exists in ... or something.

Sure, the _views resource is just an example, and might not be that
useful, but at least extending the document resource would be possible
if/when the need comes up.

= Reserved Names =

Following on from "Document Bits", would it be sensible to reserve
*all* path segments beginning with an underscore for CouchDB's use?

For instance, attachments are currently immediate children of the
document and can start with an underscore making it impossible
(without a little guess work from CouchDB as to what the user means)
to add couch-specific child resources under  document resource should
it ever want to.

CouchDB uses the underscore prefix in a lot of places already (_id,
_rev, _view, _all_docs, etc) so it would be a reasonable and natural
restriction to impose on users in my opinion.

= View API - start/end pairs =

Would it make sense to combine the startXXX and endXXX pairs into a
single range query param. For instance,

startkey=1&endkey=25 would become keyrange=[1,25] (obviously, it would
need to JSONified).

Really, really not sure about this idea, but they do seem to go
together. I guess you could even allow multiple keyrange params to
select multiple bits of the view ... although I can't really think why
you'd do that ;-).

= View API - map/reduce/rereduce control =

There are currently two view query params - group and reduce - that
control how far the map/reduce/rereduce process is taken. In fact, I
believe the group arg is ignored unless the reduce step is used. Would
it make sense to combine them into a single query param (dunno what it
would be called though ;-)) that can have a value of "map", "reduce"
or "rereduce" with the following current meaning:

	"map" => reduce=false
	"reduce" => reduce=true&group=true
	"rereduce" => reduce=true&group=false

View raw message