[O2B-1623] Document the status endpoints in the HTTP API documentation

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=<jwt>`).
@@ -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"
+```

lib/server/api-docs/index.html

@@ -58,7 +58,7 @@
 <h1>Bookkeeping HTTP API</h1>
 <p>HTTP API of the ALICE Bookkeeping. <strong>Internal use only.</strong></p>
 <blockquote>
-<p>Pilot: only the <code>tags</code> resource is documented so far.</p>
+<p>Work in progress: not every resource is documented yet. Only the sections listed below exist.</p>
 </blockquote>
 <h2>Authentication</h2>
 <p>Every request carries a JWT in the <code>token</code> <strong>query parameter</strong> (e.g. <code>GET /api/tags?token=&lt;jwt&gt;</code>).
@@ -433,6 +433,32 @@ <h2>Tags</h2>
 <pre><code class="language-bash">curl -g &quot;$BOOKKEEPING_URL/api/tags/1/logs?page[limit]=100&amp;token=$TOKEN&quot;
 </code></pre>
 </details>
+<h2>Status</h2>
+<p>Health of the Bookkeeping application and of its database.</p>
+<details>
+<summary><h3><span class="method get">GET</span> <code>/status/database</code> - Get the database connection status</h3></summary>
+
+<p>Operation id: <code>getDatabaseStatus</code></p>
+<p>Pings the database. <code>status.ok</code> is false when it cannot be reached.</p>
+<p>Responses:</p>
+<ul>
+<li><code>200</code>: The database host, port and status.</li>
+</ul>
+<pre><code class="language-bash">curl -g &quot;$BOOKKEEPING_URL/api/status/database?token=$TOKEN&quot;
+</code></pre>
+</details>
+<details>
+<summary><h3><span class="method get">GET</span> <code>/status/gui</code> - Get the status of the Bookkeeping application</h3></summary>
+
+<p>Operation id: <code>getGuiStatus</code></p>
+<p>Returns the host, port and version of the running Bookkeeping server that answered the request.</p>
+<p>Responses:</p>
+<ul>
+<li><code>200</code>: The application host, port, version and status.</li>
+</ul>
+<pre><code class="language-bash">curl -g &quot;$BOOKKEEPING_URL/api/status/gui?token=$TOKEN&quot;
+</code></pre>
+</details>
 
 </main>
 <footer>Generated from openapi.yaml by <code>npm run docs:api</code> · ALICE Bookkeeping · internal use only</footer>

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=<jwt>`).
@@ -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' }