apache / apache/bookkeeper

docs: missing HTTP API endpoints in versioned admin REST API documentation

Open
#4,795 0 comments 0 reactions 0 assignees View on GitHub
Dominant language
Java
Stars
2k
Forks
976
Avg merge
6d 15h
Merged PRs (30d)
7

Description

Is this a question, feature request, bug report, or bookkeeper proposal?

**BUG REPORT**

1. Please describe the issue you observed:

- **What did you do?**

Reviewed the versioned admin REST API documentation pages under `site3/website/versioned_docs/version-*/admin/http.md` and compared them against `HttpRouter.java` at the corresponding git tags.

- **What did you expect to see?**

All HTTP endpoints registered in `HttpRouter.java` at a given release tag should be documented in the corresponding versioned `http.md`.

- **What did you see instead?**

Several endpoints implemented in the code were absent from the versioned docs. For example:

**version-4.14.8 and version-4.15.5** — missing endpoints:
- `/api/v1/bookie/cluster_info` — returns top-level cluster info (auditor elected, bookie counts, replication state, etc.)
- `/api/v1/bookie/state/readonly` (GET + PUT) — get or set bookie read-only state
- `/api/v1/autorecovery/status` (GET + PUT) — get or set autorecovery enable status

**version-4.16.7 and version-4.17.3** — additionally missing:
- `/api/v1/bookie/state/readonly` (GET + PUT)
- `/api/v1/autorecovery/status` (GET + PUT)
- `forceMajor` / `forceMinor` optional parameters on `PUT /api/v1/bookie/gc` (introduced alongside `suspend_compaction` / `resume_compaction` in the 4.16.x line)

Note: `suspend_compaction`, `resume_compaction`, `sanity`, and `entry_location_compact` were correctly absent from the 4.14.8/4.15.5 docs — those endpoints were not registered in `HttpRouter.java` until the 4.16.x release line.

A fix for the four maintained versioned doc versions (4.14.8, 4.15.5, 4.16.7, 4.17.3) is tracked in PR #4793.

Contributor guide

Open the contributing guide

Assessment

This issue has not been assessed yet.

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.