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

lib/database/adapters/HostAdapter.js

@@ -34,12 +34,10 @@ class HostAdapter {
      * @param {SequelizeHost} databaseObject Object to convert.
      * @returns {Host} Converted entity object.
      */
-    toEntity({ id, hostname, processesExecutions, createdAt, updatedAt }) {
+    toEntity({ id, hostname, processesExecutions }) {
         return {
             id,
             hostname,
-            createdAt: createdAt ? new Date(createdAt).getTime() : createdAt,
-            updatedAt: updatedAt ? new Date(updatedAt).getTime() : updatedAt,
             processesExecutions: (processesExecutions ?? []).map(this.dplProcessExecutionAdapter.toEntity),
         };
     }

lib/database/adapters/dpl/DplDetectorAdapter.js

@@ -35,12 +35,10 @@ class DplDetectorAdapter {
      * @returns {DplDetector} Converted entity object.
      */
     toEntity(databaseObject) {
-        const { id, name, createdAt, updatedAt, processesExecutions } = databaseObject;
+        const { id, name, processesExecutions } = databaseObject;
         return {
             id,
             name,
-            createdAt: createdAt ? new Date(createdAt).getTime() : createdAt,
-            updatedAt: updatedAt ? new Date(updatedAt).getTime() : updatedAt,
             processesExecutions: (processesExecutions ?? []).map(this.dplProcessExecutionAdapter.toEntity),
         };
     }

lib/database/adapters/dpl/DplProcessAdapter.js

@@ -39,13 +39,11 @@ class DplProcessAdapter {
      * @param {SequelizeDplProcess} databaseObject Object to convert.
      * @returns {DplProcess} Converted entity object.
      */
-    toEntity({ id, name, typeId, createdAt, updatedAt, type, processesExecutions }) {
+    toEntity({ id, name, typeId, type, processesExecutions }) {
         return {
             id,
             name,
             typeId,
-            createdAt: createdAt ? new Date(createdAt).getTime() : createdAt,
-            updatedAt: updatedAt ? new Date(updatedAt).getTime() : updatedAt,
             type: type ? this.dplProcessTypeAdapter.toEntity(type) : null,
             processesExecutions: (processesExecutions ?? []).map(this.dplProcessExecutionAdapter.toEntity),
         };

lib/database/adapters/dpl/DplProcessExecutionAdapter.js

@@ -50,7 +50,7 @@ class DplProcessExecutionAdapter {
      * @returns {DplProcessExecution} Converted entity object.
      */
     toEntity(databaseObject) {
-        const { id, hostId, processId, detectorId, runNumber, args, createdAt, updatedAt, detector, host, process, run } = databaseObject;
+        const { id, hostId, processId, detectorId, runNumber, args, detector, host, process, run } = databaseObject;
 
         return {
             id,
@@ -59,8 +59,6 @@ class DplProcessExecutionAdapter {
             detectorId,
             runNumber,
             args,
-            createdAt: createdAt ? new Date(createdAt).getTime() : createdAt,
-            updatedAt: updatedAt ? new Date(updatedAt).getTime() : updatedAt,
             detector: detector ? this.dplDetectorAdapter.toEntity(detector) : null,
             host: host ? this.hostAdapter.toEntity(host) : null,
             process: process ? this.dplProcessAdapter.toEntity(process) : null,

lib/database/adapters/dpl/DplProcessTypeAdapter.js

@@ -29,12 +29,10 @@ class DplProcessTypeAdapter {
      * @param {SequelizeDplProcessType} databaseObject Object to convert.
      * @returns {DplProcessType} Converted entity object.
      */
-    toEntity({ id, label, createdAt, updatedAt }) {
+    toEntity({ id, label }) {
         return {
             id,
             label,
-            createdAt: createdAt ? new Date(createdAt).getTime() : createdAt,
-            updatedAt: updatedAt ? new Date(updatedAt).getTime() : updatedAt,
         };
     }
 

lib/domain/entities/Host.js

@@ -15,8 +15,6 @@
  * @typedef Host
  * @property {number} id
  * @property {string} hostname
- * @property {number} createdAt
- * @property {number} updatedAt
  * @property {DplProcessExecution[]} processesExecutions
  */
 

lib/domain/entities/dpl/DplDetector.js

@@ -15,8 +15,6 @@
  * @typedef DplDetector
  * @property {number} id
  * @property {string} name
- * @property {number} createdAt
- * @property {number} updatedAt
  * @property {DplProcessExecution[]} processesExecutions
  */
 

lib/domain/entities/dpl/DplProcess.js

@@ -16,8 +16,6 @@
  * @property {number} id
  * @property {string} name
  * @property {number} typeId
- * @property {number} createdAt
- * @property {number} updatedAt
  * @property {DplProcessType|null} type
  * @property {DplProcessExecution[]} processesExecutions
  */

lib/domain/entities/dpl/DplProcessExecution.js

@@ -16,11 +16,9 @@
  * @property {number} id
  * @property {number} runNumber
  * @property {number} detectorId
- * @property {string} processId
- * @property {string} hostId
- * @property {string} args
- * @property {number} createdAt
- * @property {number} updatedAt
+ * @property {number} processId
+ * @property {number} hostId
+ * @property {string|null} args
  * @property {Run|null} run
  * @property {DplDetector|null} detector
  * @property {DplProcess|null} process

lib/domain/entities/dpl/DplProcessType.js

@@ -15,8 +15,6 @@
  * @typedef DplProcessType
  * @property {number} id
  * @property {string} label
- * @property {number} createdAt
- * @property {number} updatedAt
  */
 
 /**

lib/server/api-docs/API.md

@@ -646,3 +646,95 @@ Responses:
 ```bash
 curl -g -OJ "$BOOKKEEPING_URL/api/attachments/1?token=$TOKEN"
 ```
+
+## DPL processes
+
+Processes of the data processing layer (DPL) executed during the runs, by detector, process and host.
+
+### `GET /dpl-process/detectors` - List the detectors having an executed process in a run
+
+Operation id: `listDplDetectorsWithExecutedProcesses`
+
+Returns the detectors that have at least one executed DPL process in the run, sorted by name. Not paginated. This is the first level of the
+run details tree of DPL processes: detector, then process (`/dpl-process/processes`), then host (`/dpl-process/hosts`), then executions
+(`/dpl-process/executions`).
+
+| Parameter | In | Type | Required | Notes |
+| --- | --- | --- | --- | --- |
+| `runNumber` | query | integer | yes | Run number. |
+
+Responses:
+
+- `200`: The detectors.
+- `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`: The run, the detector, the process or the host does not exist.
+
+```bash
+curl -g "$BOOKKEEPING_URL/api/dpl-process/detectors?runNumber=106&token=$TOKEN"
+```
+
+### `GET /dpl-process/processes` - List the processes executed for a detector in a run
+
+Operation id: `listDplProcessesExecutedForDetector`
+
+Returns the DPL processes that have been executed at least once in the run for the detector, sorted by name, with their type. Not paginated.
+
+| Parameter | In | Type | Required | Notes |
+| --- | --- | --- | --- | --- |
+| `runNumber` | query | integer | yes | Run number. |
+| `detectorId` | query | integer | yes | Identifier of the detector (the detectors of `GET /detectors`). |
+
+Responses:
+
+- `200`: The processes.
+- `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`: The run, the detector, the process or the host does not exist.
+
+```bash
+curl -g "$BOOKKEEPING_URL/api/dpl-process/processes?runNumber=106&detectorId=1&token=$TOKEN"
+```
+
+### `GET /dpl-process/hosts` - List the hosts on which a process was executed for a detector in a run
+
+Operation id: `listHostsExecutingDplProcess`
+
+Returns the hosts on which the DPL process has been executed at least once in the run for the detector, sorted by host name. Not paginated.
+
+| Parameter | In | Type | Required | Notes |
+| --- | --- | --- | --- | --- |
+| `runNumber` | query | integer | yes | Run number. |
+| `detectorId` | query | integer | yes | Identifier of the detector (the detectors of `GET /detectors`). |
+| `processId` | query | integer | yes | Identifier of the DPL process. |
+
+Responses:
+
+- `200`: The hosts.
+- `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`: The run, the detector, the process or the host does not exist.
+
+```bash
+curl -g "$BOOKKEEPING_URL/api/dpl-process/hosts?runNumber=106&detectorId=1&processId=1&token=$TOKEN"
+```
+
+### `GET /dpl-process/executions` - List the executions of a process on a host for a detector in a run
+
+Operation id: `listDplProcessExecutions`
+
+Returns the executions of the DPL process on the host in the run for the detector. Not paginated.
+
+| Parameter | In | Type | Required | Notes |
+| --- | --- | --- | --- | --- |
+| `runNumber` | query | integer | yes | Run number. |
+| `detectorId` | query | integer | yes | Identifier of the detector (the detectors of `GET /detectors`). |
+| `processId` | query | integer | yes | Identifier of the DPL process. |
+| `hostId` | query | integer | yes | Host identifier. |
+
+Responses:
+
+- `200`: The executions.
+- `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`: The run, the detector, the process or the host does not exist.
+
+```bash
+curl -g "$BOOKKEEPING_URL/api/dpl-process/executions?runNumber=106&detectorId=1&processId=1&hostId=1&token=$TOKEN"
+```