Skip to content

Repository navigation

[O2B-1623] Document the LHC periods statistics endpoints in the HTTP API documentation #2271

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Open
graduta wants to merge 2 commits into from
+309 −0
Open

[O2B-1623] Document the LHC periods statistics endpoints in the HTTP API documentation #2271

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
2 commits
Select commit Hold shift + click to select a range
bcf0355
[O2B-1623] Document the LHC periods statistics endpoints in the HTTP …
claude Oct 20, 2026
c43d848
[O2B-1623] Regenerate the HTTP API documentation with the LHC periods…
claude Oct 20, 2026
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
55 changes: 55 additions & 0 deletions lib/server/api-docs/API.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -459,3 +459,58 @@ Responses:
```bash
curl -g "$BOOKKEEPING_URL/api/simulationPasses/1?token=$TOKEN"
```

## LHC periods statistics

LHC periods with statistics on their physics runs.

### `GET /lhcPeriodsStatistics` - List LHC periods with their statistics

Operation id: `listLhcPeriodsStatistics`

Returns a page of LHC periods with statistics computed on their **physics runs**: number of runs, average center-of-mass energy, distinct
energies, PDP beam types and number of data and simulation passes. Default order is by id, descending.

List filters are repeated query parameters: `filter[ids][]=1&filter[ids][]=2`. A single value without `[]` is rejected. Unknown query
parameters are rejected.

| Parameter | In | Type | Required | Notes |
| --- | --- | --- | --- | --- |
| `filter[ids][]` | query | integer | no | Keep the LHC periods with one of these ids. Repeat the parameter for several values. |
| `filter[names][]` | query | string | no | Keep the LHC periods with one of these exact names. Repeat the parameter for several values. |
| `filter[years][]` | query | integer | no | Keep the LHC periods of these years. The year is read from the period name (`LHC23f` is 2023). Repeat the parameter for several values. |
| `filter[pdpBeamTypes][]` | query | string | no | Keep the LHC periods having runs of one of these PDP beam types. Repeat the parameter for several values. |
| `sort[id]` | query | string | no | Sort by id (the default is `desc`). |
| `sort[name]` | query | string | no | Sort by name. |
| `sort[avgCenterOfMassEnergy]` | query | string | no | Sort by average center-of-mass energy. |
| `sort[year]` | query | string | no | Sort by year. |
| `sort[pdpBeamTypes]` | query | string | no | Sort by PDP beam types. |
| `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 LHC periods with statistics.
- `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/lhcPeriodsStatistics?page[limit]=100&token=$TOKEN"
```

### `GET /lhcPeriodsStatistics/{lhcPeriodId}` - Get the statistics of an LHC period

Operation id: `getLhcPeriodStatistics`

| Parameter | In | Type | Required | Notes |
| --- | --- | --- | --- | --- |
| `lhcPeriodId` | path | integer | yes | LHC period identifier. |

Responses:

- `200`: The LHC period with its statistics.
- `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 LHC period has this id.

```bash
curl -g "$BOOKKEEPING_URL/api/lhcPeriodsStatistics/1?token=$TOKEN"
```
137 changes: 137 additions & 0 deletions lib/server/api-docs/index.html
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -798,6 +798,143 @@ <h2>Simulation passes</h2>
<pre><code class="language-bash">curl -g &quot;$BOOKKEEPING_URL/api/simulationPasses/1?token=$TOKEN&quot;
</code></pre>
</details>
<h2>LHC periods statistics</h2>
<p>LHC periods with statistics on their physics runs.</p>
<details>
<summary><h3><span class="method get">GET</span> <code>/lhcPeriodsStatistics</code> - List LHC periods with their statistics</h3></summary>

<p>Operation id: <code>listLhcPeriodsStatistics</code></p>
<p>Returns a page of LHC periods with statistics computed on their <strong>physics runs</strong>: number of runs, average center-of-mass energy, distinct
energies, PDP beam types and number of data and simulation passes. Default order is by id, 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. Unknown query
parameters are rejected.</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 LHC periods 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 LHC periods with one of these exact names. Repeat the parameter for several values.</td>
</tr>
<tr>
<td><code>filter[years][]</code></td>
<td>query</td>
<td>integer</td>
<td>no</td>
<td>Keep the LHC periods of these years. The year is read from the period name (<code>LHC23f</code> is 2023). Repeat the parameter for several values.</td>
</tr>
<tr>
<td><code>filter[pdpBeamTypes][]</code></td>
<td>query</td>
<td>string</td>
<td>no</td>
<td>Keep the LHC periods having runs of one of these PDP beam types. 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 (the default is <code>desc</code>).</td>
</tr>
<tr>
<td><code>sort[name]</code></td>
<td>query</td>
<td>string</td>
<td>no</td>
<td>Sort by name.</td>
</tr>
<tr>
<td><code>sort[avgCenterOfMassEnergy]</code></td>
<td>query</td>
<td>string</td>
<td>no</td>
<td>Sort by average center-of-mass energy.</td>
</tr>
<tr>
<td><code>sort[year]</code></td>
<td>query</td>
<td>string</td>
<td>no</td>
<td>Sort by year.</td>
</tr>
<tr>
<td><code>sort[pdpBeamTypes]</code></td>
<td>query</td>
<td>string</td>
<td>no</td>
<td>Sort by PDP beam types.</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 LHC periods with statistics.</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/lhcPeriodsStatistics?page[limit]=100&amp;token=$TOKEN&quot;
</code></pre>
</details>
<details>
<summary><h3><span class="method get">GET</span> <code>/lhcPeriodsStatistics/{lhcPeriodId}</code> - Get the statistics of an LHC period</h3></summary>

<p>Operation id: <code>getLhcPeriodStatistics</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>lhcPeriodId</code></td>
<td>path</td>
<td>integer</td>
<td>yes</td>
<td>LHC period identifier.</td>
</tr>
</tbody></table>
<p>Responses:</p>
<ul>
<li><code>200</code>: The LHC period with its statistics.</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 LHC period has this id.</li>
</ul>
<pre><code class="language-bash">curl -g &quot;$BOOKKEEPING_URL/api/lhcPeriodsStatistics/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>
Expand Down
117 changes: 117 additions & 0 deletions lib/server/api-docs/openapi.yaml
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -53,6 +53,8 @@ tags:
description: Data used to fill end-of-shift reports.
- name: Simulation passes
description: Monte Carlo simulation productions.
- name: LHC periods statistics
description: LHC periods with statistics on their physics runs.

paths:
/tags:
Expand Down Expand Up @@ -538,6 +540,88 @@ paths:
errors:
- { status: 404, title: Not found, detail: Simulation pass with this id (99999) could not be found }

/lhcPeriodsStatistics:
get:
tags: [LHC periods statistics]
operationId: listLhcPeriodsStatistics
summary: List LHC periods with their statistics
description: |
Returns a page of LHC periods with statistics computed on their **physics runs**: number of runs, average center-of-mass energy, distinct
energies, PDP beam types and number of data and simulation passes. Default order is by id, descending.

List filters are repeated query parameters: `filter[ids][]=1&filter[ids][]=2`. A single value without `[]` is rejected. Unknown query
parameters are rejected.
parameters:
- name: filter[ids][]
in: query
description: Keep the LHC periods with one of these ids. Repeat the parameter for several values.
schema: { type: integer }
- name: filter[names][]
in: query
description: Keep the LHC periods with one of these exact names. Repeat the parameter for several values.
schema: { type: string, examples: [LHC22b] }
- name: filter[years][]
in: query
description: Keep the LHC periods of these years. The year is read from the period name (`LHC23f` is 2023). Repeat the parameter for several values.
schema: { type: integer, examples: [2023] }
- name: filter[pdpBeamTypes][]
in: query
description: Keep the LHC periods having runs of one of these PDP beam types. Repeat the parameter for several values.
schema: { type: string, examples: [pp] }
- name: sort[id]
in: query
description: Sort by id (the default is `desc`).
schema: { $ref: '#/components/schemas/SortOrder' }
- name: sort[name]
in: query
description: Sort by name.
schema: { $ref: '#/components/schemas/SortOrder' }
- name: sort[avgCenterOfMassEnergy]
in: query
description: Sort by average center-of-mass energy.
schema: { $ref: '#/components/schemas/SortOrder' }
- name: sort[year]
in: query
description: Sort by year.
schema: { $ref: '#/components/schemas/SortOrder' }
- name: sort[pdpBeamTypes]
in: query
description: Sort by PDP beam types.
schema: { $ref: '#/components/schemas/SortOrder' }
- $ref: '#/components/parameters/PageLimit'
- $ref: '#/components/parameters/PageOffset'
responses:
'200':
description: A page of LHC periods with statistics.
content:
application/json:
schema: { $ref: '#/components/schemas/LhcPeriodStatisticsListResponse' }
'400': { $ref: '#/components/responses/ValidationError' }

/lhcPeriodsStatistics/{lhcPeriodId}:
get:
tags: [LHC periods statistics]
operationId: getLhcPeriodStatistics
summary: Get the statistics of an LHC period
parameters:
- name: lhcPeriodId
in: path
required: true
description: LHC period identifier.
schema: { type: integer }
responses:
'200':
description: The LHC period with its statistics.
content:
application/json:
schema: { $ref: '#/components/schemas/LhcPeriodStatisticsResponse' }
'400': { $ref: '#/components/responses/ValidationError' }
'404':
description: No LHC period has this id.
content:
application/json:
schema: { $ref: '#/components/schemas/ErrorResponse' }

components:
securitySchemes:
jwtQuery:
Expand Down Expand Up @@ -860,3 +944,36 @@ components:
type: array
items: { $ref: '#/components/schemas/SimulationPass' }
meta: { $ref: '#/components/schemas/PageMeta' }
LhcPeriodStatistics:
type: object
properties:
id: { type: integer }
lhcPeriod:
type: [object, 'null']
properties:
id: { type: integer }
name: { type: string, examples: [LHC22b] }
avgCenterOfMassEnergy: { type: [number, 'null'], description: Average over the physics runs. }
distinctEnergies:
type: array
description: Distinct center-of-mass energies of the physics runs.
items: { type: number }
pdpBeamTypes:
type: array
items: { type: string, examples: [pp] }
runsCount: { type: integer, description: Number of physics runs. }
dataPassesCount: { type: integer }
simulationPassesCount: { type: integer }
LhcPeriodStatisticsResponse:
type: object
required: [data]
properties:
data: { $ref: '#/components/schemas/LhcPeriodStatistics' }
LhcPeriodStatisticsListResponse:
type: object
required: [data, meta]
properties:
data:
type: array
items: { $ref: '#/components/schemas/LhcPeriodStatistics' }
meta: { $ref: '#/components/schemas/PageMeta' }
Loading