This is an automated email from the ASF dual-hosted git repository.
jerryshao pushed a commit to branch main
in repository https://gitbox.apache.org/repos/asf/gravitino.git
The following commit(s) were added to refs/heads/main by this push:
new 3851fa5d65 [#14616] docs: Correct health status casing in API
documentation (#14617)
3851fa5d65 is described below
commit 3851fa5d650ba9817ccb071cc447f7475e3b2d43
Author: Jerry Shao <[email protected]>
AuthorDate: Thu Nov 5 11:39:46 2026 +0800
[#14616] docs: Correct health status casing in API documentation (#14617)
### What changes were proposed in this pull request?
Correct the health OpenAPI enums and examples to use lowercase
`up`/`down`.
Clarify that Gravitino and Lance REST use lowercase health statuses,
while Iceberg REST uses uppercase `UP`/`DOWN`.
### Why are the changes needed?
The documented enum does not match Gravitino REST responses.
Correcting the documentation preserves existing API compatibility.
Fixes #14616
### Does this PR introduce _any_ user-facing change?
Documentation only. Runtime behavior and response values remain
unchanged.
### How was this patch tested?
- `./gradlew :docs:build`
- `git diff --check`
---
docs/health-and-readiness.md | 5 +++++
docs/iceberg-rest-service.md | 2 +-
docs/lance-rest-service.md | 3 ++-
docs/open-api/health.yaml | 24 ++++++++++++------------
4 files changed, 20 insertions(+), 14 deletions(-)
diff --git a/docs/health-and-readiness.md b/docs/health-and-readiness.md
index 877d8c59df..a51fcbc446 100644
--- a/docs/health-and-readiness.md
+++ b/docs/health-and-readiness.md
@@ -60,6 +60,11 @@ a status of `up` or `down`, and a details map that explains
a failure. On the Gr
normal check names are `httpServer` and `entityStore`. After an observed
out-of-memory error, all
three endpoints instead report the `jvm` failure described below.
+The top-level `status` and each `checks[].status` use lowercase `up`/`down` on
Gravitino
+and Lance REST, and uppercase `UP`/`DOWN` on Iceberg REST. This applies to
liveness, readiness,
+aggregate endpoints, and their root aliases, for all health results. Clients
that inspect these
+fields must account for the casing used by the service they call.
+
## Out-of-memory Failures
A Metaspace or heap `OutOfMemoryError` can leave already-loaded endpoints
responding successfully
diff --git a/docs/iceberg-rest-service.md b/docs/iceberg-rest-service.md
index 859dcd544b..d939734e5d 100644
--- a/docs/iceberg-rest-service.md
+++ b/docs/iceberg-rest-service.md
@@ -807,7 +807,7 @@ Root-level aliases are also available for global traffic
managers that require p
After an observed `OutOfMemoryError`, all health endpoints and root aliases
return 503 with a `jvm` failure until restart. See [out-of-memory
failures](health-and-readiness.md#out-of-memory-failures) for detection scope.
-All endpoints return a JSON body with the same shape as the main Gravitino
server. The `code` field is always `0`. `status` is `UP` or `DOWN`. Liveness
reports `httpServer` and readiness reports `catalogWrapperManager`.
+All endpoints return a JSON body with the same shape as the main Gravitino
server. The `code` field is always `0`. Both the top-level `status` and each
`checks[].status` use uppercase `UP` or `DOWN`, unlike the lowercase
`up`/`down` returned by Gravitino and Lance REST. Liveness reports `httpServer`
and readiness reports `catalogWrapperManager`.
Healthy response (HTTP 200):
diff --git a/docs/lance-rest-service.md b/docs/lance-rest-service.md
index 4750d8902f..8e0dba3fb6 100644
--- a/docs/lance-rest-service.md
+++ b/docs/lance-rest-service.md
@@ -246,7 +246,8 @@ Access the service at `http://localhost:9101/lance`.
The Lance REST service exposes `/lance/health/live`, `/lance/health/ready`, and
`/lance/health` on its own port. Root aliases `/health/live`, `/health/ready`,
`/health`,
and `/health.html` are also available. Readiness checks whether the namespace
wrapper
-is initialized.
+is initialized. The top-level `status` and each `checks[].status` use lowercase
+`up` or `down`, as on the main Gravitino server.
After an observed `OutOfMemoryError`, all these endpoints return HTTP 503 with
a
`jvm` failure until restart, even if the wrapper remains initialized. See
diff --git a/docs/open-api/health.yaml b/docs/open-api/health.yaml
index dd4be8bdae..0e2403e7d4 100644
--- a/docs/open-api/health.yaml
+++ b/docs/open-api/health.yaml
@@ -116,9 +116,9 @@ components:
status:
type: string
enum:
- - UP
- - DOWN
- description: Aggregate health status
+ - up
+ - down
+ description: Aggregate health status, serialized in lowercase by the
Gravitino server
checks:
type: array
description: Per-component check results
@@ -138,9 +138,9 @@ components:
status:
type: string
enum:
- - UP
- - DOWN
- description: Status of the component
+ - up
+ - down
+ description: Status of the component, serialized in lowercase by the
Gravitino server
details:
type: object
additionalProperties:
@@ -151,24 +151,24 @@ components:
HealthUp:
value:
code: 0
- status: UP
+ status: up
checks:
- name: httpServer
- status: UP
+ status: up
details: {}
- name: entityStore
- status: UP
+ status: up
details: {}
HealthDown:
value:
code: 0
- status: DOWN
+ status: down
checks:
- name: httpServer
- status: UP
+ status: up
details: {}
- name: entityStore
- status: DOWN
+ status: down
details:
reason: timeout
