> The "include_attachments" suggestion was only consistent in this one
> context, AFAICT all other uses of the same are simply "attachments"
> and I'd personally prefer the latter.
Using plural suggests that there are multiple instances of `attachments`
query parameter usage. However, the `attachments` query parameter is
currently used for only one API endpoint: `/:db/:docid`.
Nathan Vander Wilt: While first thinking that we can just reuse the `attachments`
query parameter for other API endpoints as well, I came to the
conclusion that it is better to introduce a new `include_attachments`
query parameter for the following reasons.
In the document API, attachments are sent with one particular
requested document iff the query parameter value is `true`. Depending
on whether a client requests the content type "application/json" (by
setting the "Content-Type" header accordingly) or not, attachments are
either included Base64-encoded in the document, or sent along as
separate parts of the multipart response in their binary representation.
In the view and changes API we got a collection of documents. Even if
the `attachments` (whatsoever) query parameter value is `true`, no
attachment contents will be sent unless the `include_docs` query
parameter value is also `true`. That is, the effectiveness of the
`attachments` query parameter depends on the presence and value of
another query parameter here. Moreover, in contrast to the document
API, attachments are always included Base64-encoded in the documents,
and there are no multipart responses.
Although there would be similar meaning, I don't think it would be a
good idea to use the same query parameter name. Following the
differences in semantics, it is consequential to use a different query
parameter name. This makes the differences more explicit and therefore
can help preventing users from having bad surprises.