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

lib/database/adapters/RunTypeAdapter.js

@@ -29,12 +29,10 @@ class RunTypeAdapter {
      * @param {SequelizeRunType} databaseObject Object to convert.
      * @returns {RunType} Converted entity object.
      */
-    toEntity({ id, name, createdAt, updatedAt }) {
+    toEntity({ id, name }) {
         return {
             id,
             name,
-            createdAt: new Date(createdAt).getTime(),
-            updatedAt: new Date(updatedAt).getTime(),
         };
     }
 

lib/domain/dtos/GetAllRunTypesDto.js

@@ -13,10 +13,8 @@
  */
 
 const Joi = require('joi');
-const PaginationDto = require('./PaginationDto');
 
 const QueryDto = Joi.object({
-    page: PaginationDto,
     token: Joi.string(),
 });
 

lib/domain/entities/RunType.js

@@ -16,7 +16,5 @@
  *
  * @property {number} id
  * @property {string} name
- * @property {string} createdAt
- * @property {string} updatedAt
  * @property {Run[]} runs
  */

lib/server/api-docs/API.md

@@ -287,3 +287,41 @@ Responses:
 ```bash
 curl -g "$BOOKKEEPING_URL/api/detectors?token=$TOKEN"
 ```
+
+## Run types
+
+Types of runs (e.g. calibration kinds).
+
+### `GET /runTypes` - List run types
+
+Operation id: `listRunTypes`
+
+Returns the run types ordered by name, **descending**. Not paginated: there are few run types, and the result is capped to the maximum number of
+items of the API (5000 by default). Pagination parameters are rejected.
+
+Responses:
+
+- `200`: The run types.
+- `400`: The request failed validation. HTTP status is 400 although each error's `status` field is `"422"`. `source.pointer` has the form `/data/attributes/<query|params|body>/<field>`.
+
+```bash
+curl -g "$BOOKKEEPING_URL/api/runTypes?token=$TOKEN"
+```
+
+### `GET /runTypes/{runTypeId}` - Get a run type by id
+
+Operation id: `getRunType`
+
+| Parameter | In | Type | Required | Notes |
+| --- | --- | --- | --- | --- |
+| `runTypeId` | path | integer | yes | Run type identifier. |
+
+Responses:
+
+- `200`: The run type.
+- `400`: The request failed validation. HTTP status is 400 although each error's `status` field is `"422"`. `source.pointer` has the form `/data/attributes/<query|params|body>/<field>`.
+- `404`: No run type has this id.
+
+```bash
+curl -g "$BOOKKEEPING_URL/api/runTypes/1?token=$TOKEN"
+```

lib/server/api-docs/index.html

@@ -488,6 +488,53 @@ <h2>Detectors</h2>
 <pre><code class="language-bash">curl -g &quot;$BOOKKEEPING_URL/api/detectors?token=$TOKEN&quot;
 </code></pre>
 </details>
+<h2>Run types</h2>
+<p>Types of runs (e.g. calibration kinds).</p>
+<details>
+<summary><h3><span class="method get">GET</span> <code>/runTypes</code> - List run types</h3></summary>
+
+<p>Operation id: <code>listRunTypes</code></p>
+<p>Returns the run types ordered by name, <strong>descending</strong>. Not paginated: there are few run types, and the result is capped to the maximum number of
+items of the API (5000 by default). Pagination parameters are rejected.</p>
+<p>Responses:</p>
+<ul>
+<li><code>200</code>: The run types.</li>
+<li><code>400</code>: The request failed validation. HTTP status is 400 although each error&#39;s <code>status</code> field is <code>&quot;422&quot;</code>. <code>source.pointer</code> has the form <code>/data/attributes/&lt;query|params|body&gt;/&lt;field&gt;</code>.</li>
+</ul>
+<pre><code class="language-bash">curl -g &quot;$BOOKKEEPING_URL/api/runTypes?token=$TOKEN&quot;
+</code></pre>
+</details>
+<details>
+<summary><h3><span class="method get">GET</span> <code>/runTypes/{runTypeId}</code> - Get a run type by id</h3></summary>
+
+<p>Operation id: <code>getRunType</code></p>
+<table>
+<thead>
+<tr>
+<th>Parameter</th>
+<th>In</th>
+<th>Type</th>
+<th>Required</th>
+<th>Notes</th>
+</tr>
+</thead>
+<tbody><tr>
+<td><code>runTypeId</code></td>
+<td>path</td>
+<td>integer</td>
+<td>yes</td>
+<td>Run type identifier.</td>
+</tr>
+</tbody></table>
+<p>Responses:</p>
+<ul>
+<li><code>200</code>: The run type.</li>
+<li><code>400</code>: The request failed validation. HTTP status is 400 although each error&#39;s <code>status</code> field is <code>&quot;422&quot;</code>. <code>source.pointer</code> has the form <code>/data/attributes/&lt;query|params|body&gt;/&lt;field&gt;</code>.</li>
+<li><code>404</code>: No run type has this id.</li>
+</ul>
+<pre><code class="language-bash">curl -g &quot;$BOOKKEEPING_URL/api/runTypes/1?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

@@ -43,6 +43,8 @@ tags:
     description: Addresses of the external services Bookkeeping links to.
   - name: Detectors
     description: Detectors of the ALICE experiment.
+  - name: Run types
+    description: Types of runs (e.g. calibration kinds).
 
 paths:
   /tags:
@@ -310,6 +312,53 @@ paths:
                   - { id: 17, name: ACO, type: PHYSICAL }
                   - { id: 21, name: GLO, type: QC }
 
+  /runTypes:
+    get:
+      tags: [Run types]
+      operationId: listRunTypes
+      summary: List run types
+      description: |
+        Returns the run types ordered by name, **descending**. Not paginated: there are few run types, and the result is capped to the maximum number of
+        items of the API (5000 by default). Pagination parameters are rejected.
+      responses:
+        '200':
+          description: The run types.
+          content:
+            application/json:
+              schema: { $ref: '#/components/schemas/RunTypeListResponse' }
+              example:
+                data:
+                  - { id: 3, name: CALIBRATION_VCASN_TUNING }
+                  - { id: 1, name: NONE }
+        '400': { $ref: '#/components/responses/ValidationError' }
+
+  /runTypes/{runTypeId}:
+    get:
+      tags: [Run types]
+      operationId: getRunType
+      summary: Get a run type by id
+      parameters:
+        - name: runTypeId
+          in: path
+          required: true
+          description: Run type identifier.
+          schema: { type: integer, minimum: 1 }
+      responses:
+        '200':
+          description: The run type.
+          content:
+            application/json:
+              schema: { $ref: '#/components/schemas/RunTypeResponse' }
+        '400': { $ref: '#/components/responses/ValidationError' }
+        '404':
+          description: No run type has this id.
+          content:
+            application/json:
+              schema: { $ref: '#/components/schemas/ErrorResponse' }
+              example:
+                errors:
+                  - { status: 404, title: Not found, detail: Run type with this id (999999999) could not be found }
+
 components:
   securitySchemes:
     jwtQuery:
@@ -326,6 +375,7 @@ components:
       description: Tag identifier.
       schema: { type: integer, minimum: 1 }
 
+
   responses:
     ValidationError:
       description: |
@@ -472,3 +522,21 @@ components:
         data:
           type: array
           items: { $ref: '#/components/schemas/Detector' }
+    RunType:
+      type: object
+      required: [id, name]
+      properties:
+        id: { type: integer }
+        name: { type: string, description: 'Run type name, e.g. `NONE` or `CALIBRATION_THR_SCAN`.' }
+    RunTypeResponse:
+      type: object
+      required: [data]
+      properties:
+        data: { $ref: '#/components/schemas/RunType' }
+    RunTypeListResponse:
+      type: object
+      required: [data]
+      properties:
+        data:
+          type: array
+          items: { $ref: '#/components/schemas/RunType' }

lib/server/controllers/runTypes.controller.js

@@ -12,23 +12,13 @@
  * or submit itself to any jurisdiction.
  */
 
-const {
-    runType: {
-        GetAllRunTypesUseCase,
-        GetRunTypeUseCase,
-    },
-} = require('../../usecases');
-const {
-    dtos: {
-        GetAllRunTypesDto,
-        GetRunTypeDto,
-    },
-} = require('../../domain');
+const { dtos: { GetAllRunTypesDto, GetRunTypeDto } } = require('../../domain');
 const { dtoValidator } = require('../utilities');
-const { ApiConfig } = require('../../config/index.js');
+const { runTypeService } = require('../services/runType/RunTypeService.js');
+const { updateExpressResponseFromNativeError } = require('../express/updateExpressResponseFromNativeError.js');
 
 /**
- * Get all runs.
+ * Get all run types.
  *
  * @param {Object} request The *request* object represents the HTTP request and has properties for the request query
  *                         string, parameters, body, HTTP headers, and so on.
@@ -42,25 +32,15 @@ const listRunTypes = async (request, response) => {
         return;
     }
 
-    const { count, runTypes } = await new GetAllRunTypesUseCase()
-        .execute(value);
-
-    const { query: { page: { limit = ApiConfig.pagination.limit } = {} } } = value;
-    const totalPages = Math.ceil(count / limit);
-
-    response.status(200).json({
-        data: runTypes,
-        meta: {
-            page: {
-                pageCount: totalPages,
-                totalCount: count,
-            },
-        },
-    });
+    try {
+        response.status(200).json({ data: await runTypeService.getAll() });
+    } catch (error) {
+        updateExpressResponseFromNativeError(response, error);
+    }
 };
 
 /**
- * Get run.
+ * Get a run type.
  *
  * @param {Object} request The *request* object represents the HTTP request and has properties for the request query
  *                         string, parameters, body, HTTP headers, and so on.
@@ -74,22 +54,10 @@ const getRunTypeById = async (request, response) => {
         return;
     }
 
-    const runType = await new GetRunTypeUseCase()
-        .execute(value);
-
-    if (runType === null) {
-        response.status(404).json({
-            errors: [
-                {
-                    status: '404',
-                    title: `Run with this id (${value.params.runTypeId}) could not be found`,
-                },
-            ],
-        });
-    } else {
-        response.status(200).json({
-            data: runType,
-        });
+    try {
+        response.status(200).json({ data: await runTypeService.getOneOrFail({ id: value.params.runTypeId }) });
+    } catch (error) {
+        updateExpressResponseFromNativeError(response, error);
     }
 };
 

lib/server/services/runType/RunTypeService.js

@@ -0,0 +1,50 @@
+/**
+ * @license
+ * Copyright CERN and copyright holders of ALICE O2. This software is
+ * distributed under the terms of the GNU General Public License v3 (GPL
+ * Version 3), copied verbatim in the file "COPYING".
+ *
+ * See http://alice-o2.web.cern.ch/license for full licensing information.
+ *
+ * In applying this license CERN does not waive the privileges and immunities
+ * granted to it by virtue of its status as an Intergovernmental Organization
+ * or submit itself to any jurisdiction.
+ */
+
+const { runTypeAdapter } = require('../../../database/adapters/index.js');
+const { ApiConfig } = require('../../../config/index.js');
+const { getAllRunTypes } = require('./getAllRunTypes.js');
+const { getRunTypeOrFail } = require('./getRunTypeOrFail.js');
+
+/**
+ * Global service to read run types
+ */
+class RunTypeService {
+    /**
+     * Return the run types sorted by name (descending)
+     *
+     * Run types are not paginated, but the result is capped to the maximum number of items of the API as run types can be created automatically
+     *
+     * @return {Promise<RunType[]>} the run types
+     */
+    async getAll() {
+        return (await getAllRunTypes((queryBuilder) => {
+            queryBuilder.orderBy('name', 'desc');
+            queryBuilder.limit(ApiConfig.pagination.limit);
+        })).map(runTypeAdapter.toEntity);
+    }
+
+    /**
+     * Return the run type matching the given identifier, or reject if there is none
+     *
+     * @param {RunTypeIdentifier} identifier the identifier of the run type to find
+     * @return {Promise<RunType>} resolves with the run type found or rejects with a NotFoundError
+     */
+    async getOneOrFail(identifier) {
+        return runTypeAdapter.toEntity(await getRunTypeOrFail(identifier));
+    }
+}
+
+exports.RunTypeService = RunTypeService;
+
+exports.runTypeService = new RunTypeService();

lib/server/services/runType/getAllRunTypes.js

@@ -0,0 +1,30 @@
+/**
+ * @license
+ * Copyright CERN and copyright holders of ALICE O2. This software is
+ * distributed under the terms of the GNU General Public License v3 (GPL
+ * Version 3), copied verbatim in the file "COPYING".
+ *
+ * See http://alice-o2.web.cern.ch/license for full licensing information.
+ *
+ * In applying this license CERN does not waive the privileges and immunities
+ * granted to it by virtue of its status as an Intergovernmental Organization
+ * or submit itself to any jurisdiction.
+ */
+
+const { utilities: { QueryBuilder } } = require('../../../database');
+const RunTypeRepository = require('../../../database/repositories/RunTypeRepository.js');
+
+/**
+ * Return the list of all the run types
+ *
+ * @param {Function|null} qbConfiguration function called with the run types query builder as parameter to add specific configuration to the
+ *     query
+ * @return {Promise<SequelizeRunType[]>} Promise resolving with the list of run types
+ */
+exports.getAllRunTypes = (qbConfiguration = null) => {
+    const queryBuilder = new QueryBuilder();
+    if (qbConfiguration) {
+        qbConfiguration(queryBuilder);
+    }
+    return RunTypeRepository.findAll(queryBuilder);
+};