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

lib/server/api-docs/API.md

@@ -379,3 +379,60 @@ Responses:
 ```bash
 curl -g "$BOOKKEEPING_URL/api/shift-data?shiftType=ECS&token=$TOKEN"
 ```
+
+## Simulation passes
+
+Monte Carlo simulation productions.
+
+### `GET /simulationPasses` - List simulation passes
+
+Operation id: `listSimulationPasses`
+
+Returns a page of simulation passes with their statistics (number of runs, data passes and logs).
+Default order is by name, descending.
+
+List filters are repeated query parameters: `filter[ids][]=1&filter[ids][]=2`. A single value without `[]` is rejected. Filters are combined
+with AND.
+
+| Parameter | In | Type | Required | Notes |
+| --- | --- | --- | --- | --- |
+| `filter[ids][]` | query | integer | no | Keep the simulation passes with one of these ids. Repeat the parameter for several values. |
+| `filter[names][]` | query | string | no | Keep the simulation passes with one of these exact names. Repeat the parameter for several values. |
+| `filter[lhcPeriodIds][]` | query | integer | no | Keep the simulation passes used by data passes of one of these LHC periods. Repeat the parameter for several values. |
+| `filter[dataPassIds][]` | query | integer | no | Keep the simulation passes anchored to one of these data passes. Repeat the parameter for several values. |
+| `sort[id]` | query | string | no | Sort by id. |
+| `sort[name]` | query | string | no | Sort by name (the default is `desc`). |
+| `sort[pwg]` | query | string | no | Sort by physics working group. |
+| `sort[jiraId]` | query | string | no | Sort by Jira ticket. |
+| `sort[requestedEventsCount]` | query | string | no | Sort by number of requested events. |
+| `sort[generatedEventsCount]` | query | string | no | Sort by number of generated events. |
+| `sort[outputSize]` | query | string | no | Sort by output size. |
+| `page[limit]` | query | integer | no | Maximum number of items to return. LLMs and agents must use 100 or less. |
+| `page[offset]` | query | integer | no | Number of items to skip. |
+
+Responses:
+
+- `200`: A page of simulation passes.
+- `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/simulationPasses?page[limit]=100&token=$TOKEN"
+```
+
+### `GET /simulationPasses/{id}` - Get a simulation pass by id
+
+Operation id: `getSimulationPass`
+
+| Parameter | In | Type | Required | Notes |
+| --- | --- | --- | --- | --- |
+| `id` | path | integer | yes | Simulation pass identifier. |
+
+Responses:
+
+- `200`: The simulation pass.
+- `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 simulation pass has this id.
+
+```bash
+curl -g "$BOOKKEEPING_URL/api/simulationPasses/1?token=$TOKEN"
+```

lib/server/api-docs/index.html

@@ -608,6 +608,157 @@ <h2>Shifts</h2>
 <pre><code class="language-bash">curl -g &quot;$BOOKKEEPING_URL/api/shift-data?shiftType=ECS&amp;token=$TOKEN&quot;
 </code></pre>
 </details>
+<h2>Simulation passes</h2>
+<p>Monte Carlo simulation productions.</p>
+<details>
+<summary><h3><span class="method get">GET</span> <code>/simulationPasses</code> - List simulation passes</h3></summary>
+
+<p>Operation id: <code>listSimulationPasses</code></p>
+<p>Returns a page of simulation passes with their statistics (number of runs, data passes and logs).
+Default order is by name, descending.</p>
+<p>List filters are repeated query parameters: <code>filter[ids][]=1&amp;filter[ids][]=2</code>. A single value without <code>[]</code> is rejected. Filters are combined
+with AND.</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>filter[ids][]</code></td>
+<td>query</td>
+<td>integer</td>
+<td>no</td>
+<td>Keep the simulation passes with one of these ids. Repeat the parameter for several values.</td>
+</tr>
+<tr>
+<td><code>filter[names][]</code></td>
+<td>query</td>
+<td>string</td>
+<td>no</td>
+<td>Keep the simulation passes with one of these exact names. Repeat the parameter for several values.</td>
+</tr>
+<tr>
+<td><code>filter[lhcPeriodIds][]</code></td>
+<td>query</td>
+<td>integer</td>
+<td>no</td>
+<td>Keep the simulation passes used by data passes of one of these LHC periods. Repeat the parameter for several values.</td>
+</tr>
+<tr>
+<td><code>filter[dataPassIds][]</code></td>
+<td>query</td>
+<td>integer</td>
+<td>no</td>
+<td>Keep the simulation passes anchored to one of these data passes. Repeat the parameter for several values.</td>
+</tr>
+<tr>
+<td><code>sort[id]</code></td>
+<td>query</td>
+<td>string</td>
+<td>no</td>
+<td>Sort by id.</td>
+</tr>
+<tr>
+<td><code>sort[name]</code></td>
+<td>query</td>
+<td>string</td>
+<td>no</td>
+<td>Sort by name (the default is <code>desc</code>).</td>
+</tr>
+<tr>
+<td><code>sort[pwg]</code></td>
+<td>query</td>
+<td>string</td>
+<td>no</td>
+<td>Sort by physics working group.</td>
+</tr>
+<tr>
+<td><code>sort[jiraId]</code></td>
+<td>query</td>
+<td>string</td>
+<td>no</td>
+<td>Sort by Jira ticket.</td>
+</tr>
+<tr>
+<td><code>sort[requestedEventsCount]</code></td>
+<td>query</td>
+<td>string</td>
+<td>no</td>
+<td>Sort by number of requested events.</td>
+</tr>
+<tr>
+<td><code>sort[generatedEventsCount]</code></td>
+<td>query</td>
+<td>string</td>
+<td>no</td>
+<td>Sort by number of generated events.</td>
+</tr>
+<tr>
+<td><code>sort[outputSize]</code></td>
+<td>query</td>
+<td>string</td>
+<td>no</td>
+<td>Sort by output size.</td>
+</tr>
+<tr>
+<td><code>page[limit]</code></td>
+<td>query</td>
+<td>integer</td>
+<td>no</td>
+<td>Maximum number of items to return. LLMs and agents must use 100 or less.</td>
+</tr>
+<tr>
+<td><code>page[offset]</code></td>
+<td>query</td>
+<td>integer</td>
+<td>no</td>
+<td>Number of items to skip.</td>
+</tr>
+</tbody></table>
+<p>Responses:</p>
+<ul>
+<li><code>200</code>: A page of simulation passes.</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/simulationPasses?page[limit]=100&amp;token=$TOKEN&quot;
+</code></pre>
+</details>
+<details>
+<summary><h3><span class="method get">GET</span> <code>/simulationPasses/{id}</code> - Get a simulation pass by id</h3></summary>
+
+<p>Operation id: <code>getSimulationPass</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>id</code></td>
+<td>path</td>
+<td>integer</td>
+<td>yes</td>
+<td>Simulation pass identifier.</td>
+</tr>
+</tbody></table>
+<p>Responses:</p>
+<ul>
+<li><code>200</code>: The simulation pass.</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 simulation pass has this id.</li>
+</ul>
+<pre><code class="language-bash">curl -g &quot;$BOOKKEEPING_URL/api/simulationPasses/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

@@ -49,6 +49,8 @@ tags:
     description: Counters of the central trigger processor, per run and trigger class.
   - name: Shifts
     description: Data used to fill end-of-shift reports.
+  - name: Simulation passes
+    description: Monte Carlo simulation productions.
 
 paths:
   /tags:
@@ -427,6 +429,99 @@ paths:
             application/json:
               schema: { $ref: '#/components/schemas/ErrorResponse' }
 
+  /simulationPasses:
+    get:
+      tags: [Simulation passes]
+      operationId: listSimulationPasses
+      summary: List simulation passes
+      description: |
+        Returns a page of simulation passes with their statistics (number of runs, data passes and logs).
+        Default order is by name, descending.
+
+        List filters are repeated query parameters: `filter[ids][]=1&filter[ids][]=2`. A single value without `[]` is rejected. Filters are combined
+        with AND.
+      parameters:
+        - name: filter[ids][]
+          in: query
+          description: Keep the simulation passes with one of these ids. Repeat the parameter for several values.
+          schema: { type: integer }
+        - name: filter[names][]
+          in: query
+          description: Keep the simulation passes with one of these exact names. Repeat the parameter for several values.
+          schema: { type: string, examples: [LHC23k6b] }
+        - name: filter[lhcPeriodIds][]
+          in: query
+          description: Keep the simulation passes used by data passes of one of these LHC periods. Repeat the parameter for several values.
+          schema: { type: integer }
+        - name: filter[dataPassIds][]
+          in: query
+          description: Keep the simulation passes anchored to one of these data passes. Repeat the parameter for several values.
+          schema: { type: integer }
+        - name: sort[id]
+          in: query
+          description: Sort by id.
+          schema: { $ref: '#/components/schemas/SortOrder' }
+        - name: sort[name]
+          in: query
+          description: Sort by name (the default is `desc`).
+          schema: { $ref: '#/components/schemas/SortOrder' }
+        - name: sort[pwg]
+          in: query
+          description: Sort by physics working group.
+          schema: { $ref: '#/components/schemas/SortOrder' }
+        - name: sort[jiraId]
+          in: query
+          description: Sort by Jira ticket.
+          schema: { $ref: '#/components/schemas/SortOrder' }
+        - name: sort[requestedEventsCount]
+          in: query
+          description: Sort by number of requested events.
+          schema: { $ref: '#/components/schemas/SortOrder' }
+        - name: sort[generatedEventsCount]
+          in: query
+          description: Sort by number of generated events.
+          schema: { $ref: '#/components/schemas/SortOrder' }
+        - name: sort[outputSize]
+          in: query
+          description: Sort by output size.
+          schema: { $ref: '#/components/schemas/SortOrder' }
+        - $ref: '#/components/parameters/PageLimit'
+        - $ref: '#/components/parameters/PageOffset'
+      responses:
+        '200':
+          description: A page of simulation passes.
+          content:
+            application/json:
+              schema: { $ref: '#/components/schemas/SimulationPassListResponse' }
+        '400': { $ref: '#/components/responses/ValidationError' }
+
+  /simulationPasses/{id}:
+    get:
+      tags: [Simulation passes]
+      operationId: getSimulationPass
+      summary: Get a simulation pass by id
+      parameters:
+        - name: id
+          in: path
+          required: true
+          description: Simulation pass identifier.
+          schema: { type: integer, minimum: 1 }
+      responses:
+        '200':
+          description: The simulation pass.
+          content:
+            application/json:
+              schema: { $ref: '#/components/schemas/SimulationPassResponse' }
+        '400': { $ref: '#/components/responses/ValidationError' }
+        '404':
+          description: No simulation pass has this id.
+          content:
+            application/json:
+              schema: { $ref: '#/components/schemas/ErrorResponse' }
+              example:
+                errors:
+                  - { status: 404, title: Not found, detail: Simulation pass with this id (99999) could not be found }
+
 components:
   securitySchemes:
     jwtQuery:
@@ -444,6 +539,17 @@ components:
       schema: { type: integer, minimum: 1 }
 
 
+    PageLimit:
+      name: page[limit]
+      in: query
+      description: Maximum number of items to return. LLMs and agents must use 100 or less.
+      schema: { type: integer, minimum: 1, examples: [100] }
+    PageOffset:
+      name: page[offset]
+      in: query
+      description: Number of items to skip.
+      schema: { type: integer, minimum: 0, default: 0 }
+
   responses:
     ValidationError:
       description: |
@@ -669,3 +775,47 @@ components:
       required: [data]
       properties:
         data: { $ref: '#/components/schemas/ShiftData' }
+    PageMeta:
+      type: object
+      description: Pagination information of a list response.
+      properties:
+        page:
+          type: object
+          properties:
+            pageCount: { type: integer, description: 'Number of pages for the requested `page[limit]`.' }
+            totalCount: { type: integer, description: 'Number of items matching the request, all pages included.' }
+    SortOrder:
+      type: string
+      enum: [asc, desc, ASC, DESC]
+    SimulationPass:
+      type: object
+      required: [id, name]
+      properties:
+        id: { type: integer }
+        name: { type: string, examples: [LHC23k6b] }
+        jiraId: { type: [string, 'null'], description: Jira ticket of the simulation request., examples: [SIMTICKET-2] }
+        description: { type: [string, 'null'] }
+        pwg: { type: [string, 'null'], description: Physics working group., examples: [PWGX1] }
+        requestedEventsCount: { type: [integer, 'null'] }
+        generatedEventsCount: { type: [integer, 'null'] }
+        outputSize: { type: [integer, 'null'], description: Size of the output in bytes. }
+        runsCount: { type: integer, description: Number of runs of the simulation pass. }
+        dataPassesCount: { type: integer, description: Number of data passes anchored to the simulation pass. }
+        logsCount: { type: integer, description: Number of logs linked to the simulation pass. }
+        pdpBeamTypes:
+          type: array
+          description: PDP beam types of the runs.
+          items: { type: string, examples: [PbPb] }
+    SimulationPassResponse:
+      type: object
+      required: [data]
+      properties:
+        data: { $ref: '#/components/schemas/SimulationPass' }
+    SimulationPassListResponse:
+      type: object
+      required: [data, meta]
+      properties:
+        data:
+          type: array
+          items: { $ref: '#/components/schemas/SimulationPass' }
+        meta: { $ref: '#/components/schemas/PageMeta' }