docs: update the layout/organization of the API reference
- Dominant language
- Java
- Stars
- 14.1k
- Forks
- 3.8k
- Avg merge
- 2d 58m
- Merged PRs (30d)
- 233
Description
### Description
Suggested updates to https://druid.apache.org/docs/latest/operations/api-reference.html
Some cleanup was started in this PR: https://github.com/apache/druid/pull/13213
This issue is to track other changes that have been requested:
- [ ] The single page, as it exists now, is cumbersome to use. We can break it up (using the current headings as a guide).
- [ ] The API reference should be more prominent/visible in the nav. It's currently a subitem in the Operations category.
- [ ] Not all the REST APIs are on the API reference page. We should collect them into one place for better UX.
A stretch goal would be to adopt the form factor that the API pages for SQL-based ingestion uses: https://druid.apache.org/docs/latest/multi-stage-query/api.html after the 3 bullet points are addressed.
### Motivation
The current form factor of the API reference page is not great for users, especially newer ones. We should improve it since developer facing docs are a priority.
Contributor guide
Research direction
Start with the API reference at docs/latest/operations/api-reference.html and review the cleanup already started in PR 13213. Inventory the REST APIs and current headings, then address the three listed goals: split the page, improve its navigation visibility, and collect missing APIs in one place. Treat the SQL-based ingestion API layout as a stretch goal after those changes.
Written by the indexing model from the issue text.
Assessment
- Domain
- api, documentation
- Issue type
- Documentation
- Difficulty
- 4/5
- Estimated time
- 3-5 days
- Activity status
- Stale
- Clarity
- Mostly clear
- Newbie friendliness
- 35/100