API documentation improvements

[dbutenhof]

PBENCH-829

Fill out and update API documentation.

[webbnh]

First installment....

[webbnh]

That's great stuff, it just needs a round of polishing. And, there is a question or two which is more to do with the design/implementation than the documentation, but the two should match....

[webbnh]

Very nice improvements!

However, my comments on docs/API/V1/update.md from my previous pass (1, 2, 3, 4) seem to have escaped your attention, and I have a couple of new comments and a couple of questions.

[webbnh]

Um, Dave? Your documentation improvements failed the unit tests.... 😬

[webbnh]

It would appear that Database.db_session is None. How in the ORM could that happen?

[webbnh]

@npalaska...it appears you touched the code last.... 👁️

[webbnh]

You've resolved all but one of my previous comments, but...with new updates come new comments....

There's a misspelling which should be fixed, and I'd like to see more rework around the removal of "user" as a resource; other than those, I've got a couple of questions, and the rest are lesser suggestions or nits.

[dbutenhof]

You've resolved all but #3365 (comment) of my previous comments

I truly loathe GitHub for reviews. I made an attempt to trace all the open conversations, but GitHub makes that at least 1000 times as difficult as it should be, and it's really easy to miss things. 😦

[webbnh]

As long as we're griping about GitHub's review support, I'll note that some of the replies that you posted an hour ago were composed yesterday afternoon...although that might not be entirely GitHub's fault. 😉

[webbnh]

Looks good to me...we just need a Jira ticket so we don't forget about reconciling the filtering options for /datasets/daterange with the analogous support for /datasets.

(Although, now that I look at it, /datasets/daterange doesn't look properly resource-centric...shouldn't daterange be a query parameter?...making that change might result in the convergence of the filtering options....)

[dbutenhof]

Looks good to me...we just need a Jira ticket so we don't forget about reconciling the filtering options for /datasets/daterange with the analogous support for /datasets.

(Although, now that I look at it, /datasets/daterange doesn't look properly resource-centric...shouldn't daterange be a query parameter?...making that change might result in the convergence of the filtering options....)

PBENCH-1125, by the way, which I've now coded and tested; and will post as a PR once this PR goes in so I can first modify the documentation to match. 😁

And BTW I loved the suggestion of merging this with GET /datasets?daterange so that's what I did.