Skip to content

chore: fix documentation #3334

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

Merged
Chartman123 merged 1 commit into from
May 15, 2026
+80 −21
Merged

chore: fix documentation #3334

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
1 commit
Select commit
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
57 changes: 45 additions & 12 deletions docs/API_v3.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -17,6 +17,8 @@ This file contains the API-Documentation. For more information on the returned D
- By default, the API returns data formatted as _xml_. If formatting as _json_ is desired, the request should contain the header `Accept: application/json`. For simple representation, the output presented in this document is all formatted as _json_.
- The OCS-Endpoint _always returns_ an object called `ocs`. This contains an object `meta` holding some meta-data, as well as an object `data` holding the actual data. In this document, the response-blocks only show the `data`, if not explicitely stated different.

- OpenAPI spec: a machine-readable OpenAPI description is available at `/openapi.json` in the repository root. Prefer it as source-of-truth for exact request/response shapes.

```
"ocs": {
"meta": {
Expand Down Expand Up @@ -51,7 +53,7 @@ This file contains the API-Documentation. For more information on the returned D
- `GET /api/v3/forms/{formId}/questions` to get all questions of a form
- `GET /api/v3/forms/{formId}/questions/{questionId}` to get a single question
- `POST /api/v3/forms/{formId}/questions/{questionId}/options` does now accept more options at once
- `PATCH /api/v3/forms/{formId}/questions/{questionId}/options/reorder` to reorder the options
- `PATCH /api/v3/forms/{formId}/questions/{questionId}/options` to reorder the options (request body `newOrder`, optional `optionType`)
- `POST /api/v3/forms/{formId}/submissions/files/{questionId}` to upload a file to a file question before submitting the form
- `GET /api/v3/forms/{formId}/submissions/{submissionId}` to get a single submission
- `PUT /api/v3/forms/{formId}/submissions/{submissionId}` to update an existing submission
Expand Down Expand Up @@ -524,18 +526,23 @@ Contains only manipulative question-endpoints. To retrieve options, request the
| _formId_ | Integer | ID of the form containing the question |
| _questionId_ | Integer | ID of the question, the new option will belong to |
- Parameters:
| Parameter | Type | Description |
|-----------|---------|-------------|
| _optionTexts_ | Array | Array of strings containing the new options |
- Response: The new array of option objects
- Parameters:
| Parameter | Type | Optional | Description |
|-----------|---------|----------|-------------|
| _optionTexts_ | Array | | Array of strings containing the new options |
| _optionType_ | [Option Types](DataStructure.md#Option-Types) | yes | The option-type to assign to the new options (e.g. `row`). |
- Response: The new array of option objects

```
"data": {
"id": 7,
"questionId": 1,
"order": 1,
"text": "test"
}
"data": [
{
"id": 7,
"questionId": 1,
"order": 1,
"text": "test",
"optionType": "choice"
}
]
```

### Update option properties
Expand Down Expand Up @@ -579,7 +586,7 @@ Update a single or all properties of an option-object

### Reorder options

- Endpoint: `/api/v3/forms/{formId}/questions/{questionId}/options/reorder`
- Endpoint: `/api/v3/forms/{formId}/questions/{questionId}/options`
- Method: `PATCH`
- Url-Parameter:
| Parameter | Type | Description |
Expand All @@ -590,6 +597,7 @@ Update a single or all properties of an option-object
| Parameter | Type | Description |
|-----------|---------|-------------|
| _newOrder_ | Array | Array of **all** option IDs, ordered in the desired order |
| _optionType_ | [QuestionType](DataStructure.md#question-types) | *optional* option type to reorder (e.g. `row`). |
- Restrictions: The Array **must** contain all option IDs corresponding to the specified question and **must not** contain any duplicates.
- Response: Array of optionIds and their corresponding order.

Expand Down Expand Up @@ -919,6 +927,31 @@ Store Submission to Database

- Response: **Status-Code OK**.

### Update a Submission

Update an existing submission (only allowed when `allowEditSubmissions` is set on the form).

- Endpoint: `/api/v3/forms/{formId}/submissions/{submissionId}`
- Method: `PUT`
- Url-Parameters:
| Parameter | Type | Description |
|-----------|---------|-------------|
| _formId_ | Integer | ID of the form containing the submission |
| _submissionId_ | Integer | ID of the submission to update |
- Parameters:
| Parameter | Type | Description |
|-----------|---------|-------------|
| _answers_ | Array | Array of answers (same structure as insert submission POST) |
- Restrictions:
- The form must have `allowEditSubmissions` enabled.
- Only the user who created the submission may update it.
- Answers are validated the same way as on submit.
- Response: **Status-Code OK**, as well as the id of the updated submission.

```
"data": 5
```

### Delete a single Submission

- Endpoint: `/api/v3/forms/{formId}/submissions/{submissionId}`
Expand Down
33 changes: 25 additions & 8 deletions docs/DataStructure.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -5,7 +5,7 @@

# Forms Data Structure

**State: Forms v3.3.1 - 08.10.2023**
**State: Forms v5.3.0 - tbd**

This document describes the Object-Structure, that is used within the Forms App and on Forms API v3. It does partially **not** equal the actual database structure behind.

Expand Down Expand Up @@ -120,19 +120,21 @@ The form state is used for additional states, currently following states are def

Options are predefined answer-possibilities corresponding to questions with appropriate question-type.

| Property | Type | Restrictions | Description |
| ---------- | ------- | ------------- | --------------------------------------------- |
| id | Integer | unique | An instance-wide unique id of the option |
| questionId | Integer | | The id of the question, the option belongs to |
| order | Integer | | The order of the option |
| text | String | max. 1024 ch. | The option-text |
| Property | Type | Restrictions | Description |
| ---------- | ----------------------------- | ------------- | --------------------------------------------- |
| id | Integer | unique | An instance-wide unique id of the option |
| questionId | Integer | | The id of the question, the option belongs to |
| order | Integer | | The order of the option |
| text | String | max. 1024 ch. | The option-text |
| optionType | [Option Types](#option-types) | | The visual/semantic type of the option. |

```
{
"id": 1,
"questionId": 1,
"order": 1,
"text": "Option 1"
"text": "Option 1",
"optionType": "choice"
}
```

Expand Down Expand Up @@ -262,3 +264,18 @@ Optional extra settings for some [Question Types](#question-types)
| `optionsHighest` | `linearscale` | Integer | `2, 3, 4, 5, 6, 7, 8, 9, 10` | Set the highest value of the scale, default: `5` |
| `optionsLabelLowest` | `linearscale` | string | - | Set the label of the lowest value, default: `'Strongly disagree'` |
| `optionsLabelHighest` | `linearscale` | string | - | Set the label of the highest value, default: `'Strongly agree'` |
| `columns` | `grid` | Array | - | Array of column identifiers / labels for grid questions |
| `rows` | `grid` | Array | - | Array of row identifiers / labels for grid questions |
| `questionType` | `grid` | String | `checkbox`, `number`, `radio` | Type of cell for grid questions (checkbox, numeric input, or radio) |

### Option Types

Supported option types and their intended usage.

| Type-ID | Description |
| -------- | ------------------------------------------------------------------------------------------ |
| `choice` | Standard selectable option used by `dropdown`, `multiple` and `multiple_unique` questions. |
| `row` | Represents a row header when rendering options in a grid-style question. |
| `column` | Represents a column header when rendering options in a grid-style question. |

`row` and `column` option types are primarily used together with `grid` question types to build a two-dimensional selection matrix. `choice` is the default for normal option lists.
3 changes: 2 additions & 1 deletion lib/ResponseDefinitions.php
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -12,7 +12,8 @@
* id: int,
* questionId: int|float,
* text: string,
* order: ?int
* order: ?int,
* optionType?: "choice"|"row"|"column"
* }
*
* @psalm-type FormsOrder = array{
Expand Down
8 changes: 8 additions & 0 deletions openapi.json
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -311,6 +311,14 @@
"type": "integer",
"format": "int64",
"nullable": true
},
"optionType": {
"type": "string",
"enum": [
"choice",
"row",
"column"
]
}
}
},
Expand Down
Loading