I really don't like having separate APIs for one doc vs. multiple docs...
I don't think anyone suggested that?
what was suggested was a new request param (i suggested json.command=true|false), that would indicate when a top level JSON object should be interpreted as a set of commands, or as a single document.
if this request param exists, then a new sample configuration could be supplied (noble suggested /update/json/doc - i would suggest /update/json/docs (plural) might be better) which could have a <lst name="defaults"/> block setting json.command=true ... which would mean you could send either one doc or multiple docs to that endpoint, and they would just plain work. if you use /update or /update/json then for backcompat reasons, a top level JSON object would be interpreted as a list of commands – but you could override that with json.command=true in the request.
How about deprecating the existing approach in favor a new one that properly captures commands, single docs, and multiple docs and is clean for users?
I'm not sure i understand what you are proposing? .. there are only 3 "top level" constructs we could have in a valid JSON document: arrays, objects, and literals – if you want both top level objects / top level arrays to be interpreted as a doc / list of docs that doesn't leave much to put commands (only the most trivial command could be specified by a top level string/number primitive.
If folks feel like sending single documents should be the "default" and commands should be considered abnormal (a sentiment i generally agree with, particularly since most basic commands can already be sent as request params) then i already made a suggestion to how to move forward with that goal:
we can also change the default value of the new request param (and thus, the default behavior) in 5.0 so that by default we assume everything is a doc, and you have to send "json.command=true" if you want your top level braces to be interpreted as starting a set of commands.
Ease of use has to be all about the user's data and their questions for it, not about idiosyncrasies in API design to workaround previous approaches.
Nothing in the suggestion Noble and i coalesced towards has anything to do with "working around" the existing API – it's about ensuring that as the API evolves to be more freindly towards new users, we don't alienate existing users by breaking their shit if we don't have to, and giving them an easy way to edit their config to make their shit keep working if we change the default behavior.