Show and List functions let you transform documents and view results into whatever you want it to be. You could add hyperlinks for resource discovery.

http://wiki.apache.org/couchdb/Formatting_with_Show_and_List

The rewriter and vhosts don’t have documentation yet (they were added in the last weeks). In short, the rewriter lets you map any url /db/_design/doc/_rewrite/* to whatever else. This alone doesn’t help much, but in combination with vhosts, you gain full control over the CouchDB URL space. It simply maps http://example.com/ to /db/_design/doc/_rewrite based on the request Host header.

Together with shows and lists you can make fully-hypertexty CouchDB.

For the content-type, both is correct :) CouchDB assumes a “parse this as JSON” on the client and then the client can do whatever; there is no implied semantics. It does though reserve the _* namespace for properties (_id, _rev. etc). So application/json+couchdb would be more appropriate, but that wouldn’t fly with any clients in the wild.

(even worse theoretically, by default CouchDB sends text/plain with the JSON so browsers render the JSON instead of offering a download. Only if you request with application/json, you get that content type. But this is a major practicality win over the “pure” solution)

Cheers
Jan
–

Regarding the message self-descriptiveness: When you use a generic format, understanding the processing intent requires out of band knowledge (unless the intent really only is: “parse this as JSON”. IOW, the real meaning of the message can not be inferred from the message itself.

However, the question is whether that is a useful requirement for database interactions because the database is not a service with specific application semantics.

It is an interesting point because you could place all the necessary processing semantics into headers and just treat the body as somewhat opaque payload (like a PDF is for example). Let me look at the hypermedia support you mentioned, that seems related.

Thanks,
Jan

thanks for the great writeup. We’ve had this discussion quite a few times. While out of the box the hypermedia constraint is not adhered, you can make CouchDB a fully self-descriptive hypermedia source using a combination of show and list functions, the rewriter and vhosts.

I don’t really follow the HTTP type II exclusion thing. Would we have to use application/json+couchdbdocument or somesuch?

Either way, both “relaxations” from pure REST evolved out of practical experience.; )

Thanks again!

Cheers
Jan
–