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 string... 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 cacheability). == 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 http://jchris.mfdz.com
