ricellis commented on PR #4710:
URL: https://github.com/apache/couchdb/pull/4710#issuecomment-1715549181
Apologies for the delay in commenting here, I missed it initially in
vacation season.
>Appreciating the difficulties with augmenting existing endpoints, I think
it's worth considering adding "selector" and "fields" support to the
existing _all_docs, view and search endpoints.
I can see the appeal of this suggestion as a neat way to direct mango-style
queries to a specific index without the need to add additional endpoints.
However, the problem I see is that the response structure for view-like things,
searches and mango queries are all a bit different.
I'd be completely opposed to different response structures being returned
depending on the request properties. For example IMO a call to `_all_docs` with
a `selector` should definitely not return an array of `"docs":[{…},…]` like
`_find` does because it does not conform with the normally expected pattern for
`_all_docs` repsonses of `"rows":[{…"doc":{…}},…]`.
That kind of response structure toggling makes using endpoints unwieldy and
confusing for users and also makes them hard to describe accurately and
correctly in tooling and documentation.
To go down that route I'd say the responses would need to be transformed (or
maybe it is actually _not_ transformed) from the underlying index response to
retain the existing structures used by the endpoints being augmented. That
might in turn result in a loss of fidelity for some things and although
additional response properties could be added relatively painlessly a
proliferation of additional response properties that are only populated under
certain request conditions is also not very user friendly (e.g. adding a
`bookmark` that is only populated with a `selector` but not on a normal
`_all_docs`, or `execution_stats` etc).
Further I think consideration of the impact on the request options is also
needed, like how combinations could (or could _appear_ to) operate. For example:
what would it mean to provide a `selector` to a view-like endpoint with
`include_docs=false`?
or request `fields=["foo","bar"]&include_docs=true` on a normal view-like
request?
The more APIs are dual-purposed and additional options bolted onto existing
endpoints the more potential combinations surface that seem to make sense to
users, but are invalid in the implementation. Again this leads to APIs that are
harder to document and use. It isn't great for usability to have to fathom a
giant matrix of option combinations from the manual. Sure validation can be
added, but even then potentially making multiple requests getting `400`
responses before landing on a valid combination isn't a good experience.
--
This is an automated message from the Apache Git Service.
To respond to the message, please log on to GitHub and use the
URL above to go to the specific comment.
To unsubscribe, e-mail: [email protected]
For queries about this service, please contact Infrastructure at:
[email protected]
