apache / apache/druid

docs: update the layout/organization of the API reference

Open
#13,239 0 comments 0 reactions 0 assignees View on GitHub
Area - Documentation Contributions Welcome
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

Open the contributing 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

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.