api: change API page formatting

[317brian]

The current API page has the parent as the bulleted indented entry and the child as the unindented entry. I think this goes against most user expectations of having the bulleted indented entry being the child. This PR makes that change.

This PR has:

• [x] been self-reviewed.

[paul-rogers]

Wonderful! The current format has long been a struggle for me: it just seems jumbled.

Note on placement: burying the API docs in "Operations" has always seemed odd." I know it is a heavy lift, but would be great if we had a "API" section. Related: not all the REST APIs are on the API page. Some are sprinkled elsewhere. So, would be great to put them in one place, with references where needed.

While I'm asking for the world, having API as one big page is cumbersome: seldom do I need to see everything in one go. Perhaps we can break it down into multiple pages, each focused on some related topic. (The current headings might suggest a first cut.)

Suggestion: we don't need the HTTP methods as headers, just put the method in with the URL. We don't really need the bullets. The result is that there is more room for formatted explanations. Example:

Process Information

GET /status

Returns the Druid version, loaded extensions, memory used, total memory and other useful information about the process.

GET /status/health

An endpoint that always returns a boolean "true" value with a 200 OK response, useful for automated health checks.

GET /status/properties

Returns the current configuration properties of the process.

POST /mode/turbo

Posts a request to double the speed of your server.

Deprecated: Turbo mode is now standard in Druid since version 0.12.

[317brian]

Thanks for taking a look @paul-rogers! It is indeed a massive page, so I'm just making small pokes at it until we get it in a good state (ie looking more like the API pages I did for MSQ).

That's a good suggestion, and I like the look of it. Will make the changes.

[317brian]

47a9227 makes the docs look like this based on Paul's suggestion:

It also had the benefit of clarifying which endpoint some of the notes belong to.

We'll tackle the breakup and moving around in a subsequent PR.

[kfaraz]

@317brian , thanks for the quick fix! You might need to update some other files to fix broken links.

From the failed build logs:

Could not find anchor '#post-5' in '/docs/operations/api-reference.html' linked from './build/ApacheDruid/docs/data-management/automatic-compaction.html'
Could not find anchor '#post-4' in '/docs/operations/api-reference.html' linked from './build/ApacheDruid/docs/data-management/automatic-compaction.html'
Could not find anchor '#delete-1' in '/docs/operations/api-reference.html' linked from './build/ApacheDruid/docs/data-management/automatic-compaction.html'
Could not find anchor '#get-10' in '/docs/operations/api-reference.html' linked from './build/ApacheDruid/docs/data-management/automatic-compaction.html'
Could not find anchor '#task-submit' in '/docs/operations/api-reference.html' linked from './build/ApacheDruid/docs/ingestion/index.html'
Could not find anchor '#task-submit' in '/docs/operations/api-reference.html' linked from './build/ApacheDruid/docs/ingestion/index.html'

There are 6 issues

[paul-rogers]

@317brian thanks much for making the format change. Looking forward to the other changes over time. Each improvement will make the monster page easier to use.