Distinguish between paths, ids, and names

[cmbrandenburg]

The problem

The couchdb crate's API in v0.3.0 in many places uses a path type where the CouchDB server returns a mere id or name—e.g., the path in the Document struct instead of a document id, the path field in the ViewRow struct instead of a view name. The rationale for v0.3.0 is that the use of path types improves type-safety.

However, the path type causes an “impedance” mismatch between the crate and the CouchDB API. Specifically, there are two problems.

1. The use of a path type sometimes requires an extra allocation and sometimes requires extra move operations when deserializing. An example of both is deserializing a document. This requires first deserializing to a “raw” instance that contains the document id, which is the value returned by the CouchDB server, and then prepending the document name to the document id to construct a DocumentPath. This requires an extra allocation and moving all values from the raw document type to the final Document type. The application may need none of this extra work—say, if the application never uses the path field.
2. Sometimes the use of a path type is awkward.

As an example of awkwardness, consider how to add change notifications to the crate API (#12 and #14). A command to GET change notifications would require a DatabasePath (GET /db/_changes), and applying a filter would require—to remain consistent with the v0.3.0 style—a new FilterPath type containing the database path. This creates a hole in the crate's API whereby the application could apply a filter whose path specifies a database different from the one specified for the change notification command. Whereas, the CouchDB API merely needs a filter id, i.e., ?filter=design-doc/filter-name.

Proposed solution

The couchdb crate API should distinguish between paths, ids, and names.

• A path is a full name of a CouchDB resource, e.g., /db, /db/doc, /db/_design/doc/_view/view—same as in v0.3.0, though perhaps we should add the forward slash to match the CouchDB API documentation?
• An id identifies a CouchDB resource relative to some assumed database, e.g., v0.3.0 DocumentId type, or a filter id such as design-doc/filter-name.
• A name is the single, last component of a path for a resource, e.g., doc from /db/doc and view from /db/_design/doc/_view/view.

The CouchDB API uses all three: paths, ids, and names. This proposal is to change the couchdb crate's API to match the CouchDB API so that for any type or command that works with, say, an id, then the crate API will use an id, not a path.