From eed3a451bc4c1ede7519497c8271cca1465d9c15 Mon Sep 17 00:00:00 2001 From: "Claude Sonnet 5.5" Date: Tue, 20 Oct 2026 14:53:42 +0200 Subject: [PATCH 1/2] [O2B-1623] Document the status endpoints in the HTTP API specification Add GET /status/database and GET /status/gui, and reword the work-in-progress note now that more than one resource is documented. --- lib/server/api-docs/openapi.yaml | 52 +++++++++++++++++++++++++++++++- 1 file changed, 51 insertions(+), 1 deletion(-) diff --git a/lib/server/api-docs/openapi.yaml b/lib/server/api-docs/openapi.yaml index 213de05495..d865d4f7b7 100644 --- a/lib/server/api-docs/openapi.yaml +++ b/lib/server/api-docs/openapi.yaml @@ -5,7 +5,7 @@ info: description: | HTTP API of the ALICE Bookkeeping. **Internal use only.** - > Pilot: only the `tags` resource is documented so far. + > Work in progress: not every resource is documented yet. Only the sections listed below exist. ## Authentication Every request carries a JWT in the `token` **query parameter** (e.g. `GET /api/tags?token=`). @@ -37,6 +37,8 @@ security: tags: - name: Tags description: Labels attached to logs (and runs). Each tag may notify an e-mail list and a Mattermost channel. + - name: Status + description: Health of the Bookkeeping application and of its database. paths: /tags: @@ -235,6 +237,36 @@ paths: '400': { $ref: '#/components/responses/ValidationError' } '404': { $ref: '#/components/responses/NotFound' } + /status/database: + get: + tags: [Status] + operationId: getDatabaseStatus + summary: Get the database connection status + description: Pings the database. `status.ok` is false when it cannot be reached. + responses: + '200': + description: The database host, port and status. + content: + application/json: + schema: { $ref: '#/components/schemas/ServiceStatusResponse' } + example: + data: { host: database, port: 3306, status: { ok: true, configured: true } } + + /status/gui: + get: + tags: [Status] + operationId: getGuiStatus + summary: Get the status of the Bookkeeping application + description: Returns the host, port and version of the running Bookkeeping server that answered the request. + responses: + '200': + description: The application host, port, version and status. + content: + application/json: + schema: { $ref: '#/components/schemas/ServiceStatusResponse' } + example: + data: { host: localhost, port: 4000, version: 1.20.0, status: { ok: true, configured: true } } + components: securitySchemes: jwtQuery: @@ -350,3 +382,21 @@ components: type: object properties: pointer: { type: string } + ServiceStatus: + type: object + required: [host, port, status] + properties: + host: { type: string } + port: { type: integer } + version: { type: string, description: Version of the Bookkeeping application. Only present on the application status. } + status: + type: object + required: [ok, configured] + properties: + ok: { type: boolean, description: False when the service cannot be reached. } + configured: { type: boolean } + ServiceStatusResponse: + type: object + required: [data] + properties: + data: { $ref: '#/components/schemas/ServiceStatus' } From 370666f03a6148e588223f1912b86f35aca8c96f Mon Sep 17 00:00:00 2001 From: "Claude Sonnet 5.5" Date: Tue, 20 Oct 2026 14:53:42 +0200 Subject: [PATCH 2/2] [O2B-1623] Regenerate the HTTP API documentation with the status endpoints --- lib/server/api-docs/API.md | 34 +++++++++++++++++++++++++++++++++- lib/server/api-docs/index.html | 28 +++++++++++++++++++++++++++- 2 files changed, 60 insertions(+), 2 deletions(-) diff --git a/lib/server/api-docs/API.md b/lib/server/api-docs/API.md index dd43a65d5a..cd0e49775e 100644 --- a/lib/server/api-docs/API.md +++ b/lib/server/api-docs/API.md @@ -3,7 +3,7 @@ HTTP API of the ALICE Bookkeeping. **Internal use only.** -> Pilot: only the `tags` resource is documented so far. +> Work in progress: not every resource is documented yet. Only the sections listed below exist. ## Authentication Every request carries a JWT in the `token` **query parameter** (e.g. `GET /api/tags?token=`). @@ -218,3 +218,35 @@ Responses: ```bash curl -g "$BOOKKEEPING_URL/api/tags/1/logs?page[limit]=100&token=$TOKEN" ``` + +## Status + +Health of the Bookkeeping application and of its database. + +### `GET /status/database` - Get the database connection status + +Operation id: `getDatabaseStatus` + +Pings the database. `status.ok` is false when it cannot be reached. + +Responses: + +- `200`: The database host, port and status. + +```bash +curl -g "$BOOKKEEPING_URL/api/status/database?token=$TOKEN" +``` + +### `GET /status/gui` - Get the status of the Bookkeeping application + +Operation id: `getGuiStatus` + +Returns the host, port and version of the running Bookkeeping server that answered the request. + +Responses: + +- `200`: The application host, port, version and status. + +```bash +curl -g "$BOOKKEEPING_URL/api/status/gui?token=$TOKEN" +``` diff --git a/lib/server/api-docs/index.html b/lib/server/api-docs/index.html index 328c55d55c..bc843e20c8 100644 --- a/lib/server/api-docs/index.html +++ b/lib/server/api-docs/index.html @@ -58,7 +58,7 @@

Bookkeeping HTTP API

HTTP API of the ALICE Bookkeeping. Internal use only.

-

Pilot: only the tags resource is documented so far.

+

Work in progress: not every resource is documented yet. Only the sections listed below exist.

Authentication

Every request carries a JWT in the token query parameter (e.g. GET /api/tags?token=<jwt>). @@ -433,6 +433,32 @@

Tags

curl -g "$BOOKKEEPING_URL/api/tags/1/logs?page[limit]=100&token=$TOKEN"
+

Status

+

Health of the Bookkeeping application and of its database.

+
+

GET /status/database - Get the database connection status

 + +

Operation id: getDatabaseStatus

+

Pings the database. status.ok is false when it cannot be reached.

+

Responses:

+
    +
  • 200: The database host, port and status.
    • +
+
curl -g "$BOOKKEEPING_URL/api/status/database?token=$TOKEN"
+
+
+
+

GET /status/gui - Get the status of the Bookkeeping application

 + +

Operation id: getGuiStatus

+

Returns the host, port and version of the running Bookkeeping server that answered the request.

+

Responses:

+
    +
  • 200: The application host, port, version and status.
    • +
+
curl -g "$BOOKKEEPING_URL/api/status/gui?token=$TOKEN"
+
+