From 271101b4a6d0fa4015f37d0fdad2d008b82e802d Mon Sep 17 00:00:00 2001 From: Viktor Diezel Date: Wed, 6 Aug 2025 21:16:46 +0200 Subject: [PATCH 01/30] docs: minimal updates required for latest mkdocs version Signed-off-by: Viktor Diezel --- README.md | 4 +- docs/API.md | 483 +++++++++++++++++----------------- docs/Markdown.md | 4 +- docs/User_documentation_en.md | 2 + mkdocs.yml | 4 +- 5 files changed, 252 insertions(+), 245 deletions(-) diff --git a/README.md b/README.md index c115043e4b..b8cb3a655a 100644 --- a/README.md +++ b/README.md @@ -21,12 +21,12 @@ Deck is a kanban style organization tool aimed at personal planning and project ![Deck - Manage cards on your board](http://download.bitgrid.net/nextcloud/deck/screenshots/1.0/Deck-2.png) -### Mobile apps +## Mobile apps - [Nextcloud Deck app for Android](https://github.com/stefan-niedermann/nextcloud-deck) - It is available in [F-Droid](https://f-droid.org/de/packages/it.niedermann.nextcloud.deck/) and the [Google Play Store](https://play.google.com/store/apps/details?id=it.niedermann.nextcloud.deck.play) - [Nextcloud Deck app for iOS](https://github.com/StCyr/deck-react-native) - It is available in [Apple App store](https://apps.apple.com/ml/app/nextcloud-deck/id1570892788) -### 3rd-Party Integrations +## 3rd-Party Integrations - [trello-to-deck](https://github.com/maxammann/trello-to-deck) - Migrates cards from Trello - [mail2deck](https://github.com/newroco/mail2deck) - Provides an "email in" solution diff --git a/docs/API.md b/docs/API.md index 6fb4ba540d..6325f97fb7 100644 --- a/docs/API.md +++ b/docs/API.md @@ -2,15 +2,18 @@ - SPDX-FileCopyrightText: 2018 Nextcloud GmbH and Nextcloud contributors - SPDX-License-Identifier: AGPL-3.0-or-later --> + +# REST API + The REST API provides access for authenticated users to their data inside the Deck app. To get a better understanding of Decks data models and their relations, please have a look at the [data structure](structure.md) documentation. -# Prerequisites +## Prerequisites - All requests require a `OCS-APIRequest` HTTP header to be set to `true` and a `Content-Type` of `application/json`. - The API is located at https://nextcloud.local/index.php/apps/deck/api/v1.0 - All request parameters are required, unless otherwise specified -## Naming +### Naming - Board is the project like grouping of tasks that can be shared to different users and groups @@ -20,9 +23,9 @@ The REST API provides access for authenticated users to their data inside the De - Labels are defined on a board level and can be assigned to any number of cards -## Global responses +### Global responses -### 400 Bad request +#### 400 Bad request In case the request is invalid, e.g. because a parameter is missing or an invalid value has been transmitted, a 400 error will be returned: @@ -33,7 +36,7 @@ In case the request is invalid, e.g. because a parameter is missing or an invali } ``` -### 403 Permission denied +#### 403 Permission denied In any case a user doesn't have access to a requested entity, a 403 error will be returned: @@ -44,15 +47,15 @@ In any case a user doesn't have access to a requested entity, a 403 error will b } ``` -## Formats +### Formats -### Date +#### Date Datetime values in request data need to be provided in ISO-8601. Example: 2020-01-20T09:52:43+00:00 -## Headers +### Headers -### If-Modified-Since +#### If-Modified-Since Some index endpoints support limiting the result set to entries that have been changed since the given time. The supported date formats are: @@ -72,7 +75,7 @@ curl -u admin:admin -X GET \ -H "If-Modified-Since: Mon, 05 Nov 2018 09:28:00 GMT" ``` -### ETag +#### ETag An ETag header is returned in order to determine if further child elements have been updated for the following endpoints: @@ -97,14 +100,14 @@ If available the ETag will also be part of JSON response objects as shown below } ``` -# Changelog +## Changelog -## API version 1.0 +### API version 1.0 - Deck >=1.0.0: The maximum length of the card title has been extended from 100 to 255 characters - Deck >=1.0.0: The API will now return a 400 Bad request response if the length limitation of a board, stack or card title is exceeded -## API version 1.1 +### API version 1.1 This API version has become available with **Deck 1.3.0**. @@ -114,7 +117,7 @@ This API version has become available with **Deck 1.3.0**. - Prior to Deck version v1.3.0 (API v1.0), attachments were stored within deck. For this type of attachments `deck_file` was used as the default type of attachments - Starting with Deck version 1.3.0 (API v1.1) files are stored within the users regular Nextcloud files and the type `file` has been introduced for that -## API version 1.2 (unreleased) +### API version 1.2 (unreleased) - Endpoints for the new import functionality have been added: - [GET /boards/import/getSystems - Import a board](#get-boardsimportgetsystems-import-a-board) @@ -122,25 +125,25 @@ This API version has become available with **Deck 1.3.0**. - [POST /boards/import - Import a board](#post-boardsimport-import-a-board) - The `done` property was added to cards -# Endpoints +## Endpoints -## Boards +### Boards -### GET /boards - Get a list of boards +#### GET /boards - Get a list of boards -#### Headers +##### Headers The board list endpoint supports setting an `If-Modified-Since` header to limit the results to entities that are changed after the provided time. -#### Request parameters +##### Request parameters | Parameter | Type | Description | | --------- | ------- | ---------------------------- | | details | Bool | **Optional** Enhance boards with details about labels, stacks and users | -#### Response +##### Response -##### 200 Success +###### 200 Success Returns an array of board items @@ -176,9 +179,9 @@ Returns an array of board items ] ``` -### POST /boards - Create a new board +#### POST /boards - Create a new board -#### Request body +##### Request body | Parameter | Type | Description | | --------- | ------ | ---------------------------------------------------- | @@ -192,9 +195,9 @@ Returns an array of board items } ``` -#### Response +##### Response -##### 200 Success +###### 200 Success ```json { @@ -250,21 +253,21 @@ Returns an array of board items } ``` -##### 403 Forbidden +###### 403 Forbidden A 403 response might be returned if the users ability to create new boards has been disabled by the administrator. For checking this before, see the `canCreateBoards` value in the [Nextcloud capabilties](./API-Nextcloud.md). -### GET /boards/{boardId} - Get board details +#### GET /boards/{boardId} - Get board details -#### Request parameters +##### Request parameters | Parameter | Type | Description | | --------- | ------- | ---------------------------- | | boardId | Integer | The id of the board to fetch | -#### Response +##### Response -##### 200 Success +###### 200 Success ```json { @@ -325,9 +328,9 @@ A 403 response might be returned if the users ability to create new boards has b } ``` -### PUT /boards/{boardId} - Update board details +#### PUT /boards/{boardId} - Update board details -#### Request body +##### Request body | Parameter | Type | Description | | --------- | ------ | ---------------------------------------------------- | @@ -343,13 +346,13 @@ A 403 response might be returned if the users ability to create new boards has b } ``` -#### Response +##### Response -##### 200 Success +###### 200 Success -### PUT /boards/{boardId}/stacks/{stackId}/cards/{cardId}/archive - Archive a card +#### PUT /boards/{boardId}/stacks/{stackId}/cards/{cardId}/archive - Archive a card -#### Request parameters +##### Request parameters | Parameter | Type | Description | | --------- | ------- | --------------------------------------- | @@ -357,13 +360,13 @@ A 403 response might be returned if the users ability to create new boards has b | stackId | Integer | The id of the stack the card belongs to | | cardId | Integer | The id of the card | -#### Response +##### Response -##### 200 Success +###### 200 Success -### PUT /boards/{boardId}/stacks/{stackId}/cards/{cardId}/unarchive - Unarchive a card +#### PUT /boards/{boardId}/stacks/{stackId}/cards/{cardId}/unarchive - Unarchive a card -#### Request parameters +##### Request parameters | Parameter | Type | Description | | --------- | ------- | --------------------------------------- | @@ -371,37 +374,37 @@ A 403 response might be returned if the users ability to create new boards has b | stackId | Integer | The id of the stack the card belongs to | | cardId | Integer | The id of the card | -#### Response +##### Response -##### 200 Success +###### 200 Success -### DELETE /boards/{boardId} - Delete a board +#### DELETE /boards/{boardId} - Delete a board -#### Request parameters +##### Request parameters | Parameter | Type | Description | | --------- | ------- | ---------------------------- | | boardId | Integer | The id of the board to fetch | -#### Response +##### Response -##### 200 Success +###### 200 Success -### POST /boards/{boardId}/undo_delete - Restore a deleted board +#### POST /boards/{boardId}/undo_delete - Restore a deleted board -#### Request parameters +##### Request parameters | Parameter | Type | Description | | --------- | ------- | ---------------------------- | | boardId | Integer | The id of the board to fetch | -#### Response +##### Response -##### 200 Success +###### 200 Success -### POST /boards/{boardId}/acl - Add new acl rule +#### POST /boards/{boardId}/acl - Add new acl rule -#### Request body +##### Request body | Parameter | Type | Description | | --------- | ------ | ---------------------------------------------------- | @@ -411,14 +414,14 @@ A 403 response might be returned if the users ability to create new boards has b | permissionShare | Bool | Setting if the participant has sharing permissions | | permissionManage | Bool | Setting if the participant has management permissions | -##### Supported participant types: +###### Supported participant types: - 0 User - 1 Group - 7 Circle -#### Response +##### Response -##### 200 Success +###### 200 Success ```json [{ @@ -437,9 +440,9 @@ A 403 response might be returned if the users ability to create new boards has b }] ``` -### PUT /boards/{boardId}/acl/{aclId} - Update an acl rule +#### PUT /boards/{boardId}/acl/{aclId} - Update an acl rule -#### Request parameters +##### Request parameters | Parameter | Type | Description | | --------- | ------ | ---------------------------------------------------- | @@ -447,15 +450,15 @@ A 403 response might be returned if the users ability to create new boards has b | permissionShare | Bool | Setting if the participant has sharing permissions | | permissionManage | Bool | Setting if the participant has management permissions | -#### Response +##### Response -##### 200 Success +###### 200 Success -### POST /boards/{boardId}/clone - Clone a board +#### POST /boards/{boardId}/clone - Clone a board Creates a copy of the board. -#### Request body +##### Request body | Parameter | Type | Description | | --------- | ------ | ---------------------------------------------------- | @@ -466,32 +469,32 @@ Creates a copy of the board. | moveCardsToLeftStack | Bool | Setting if all cards should be moved to the most left column (useful for To-Do / Doing / Done boards) (Default: false) | | restoreArchivedCards | Bool | Setting if the archived cards should be unarchived (Default: false) | -#### Response +##### Response -##### 200 Success +###### 200 Success -### DELETE /boards/{boardId}/acl/{aclId} - Delete an acl rule +#### DELETE /boards/{boardId}/acl/{aclId} - Delete an acl rule -#### Response +##### Response -##### 200 Success +###### 200 Success -## Stacks +### Stacks -### GET /boards/{boardId}/stacks - Get stacks +#### GET /boards/{boardId}/stacks - Get stacks -#### Headers +##### Headers The board list endpoint supports setting an `If-Modified-Since` header to limit the results to entities that are changed after the provided time. -#### Request parameters +##### Request parameters | Parameter | Type | Description | | --------- | ------- | ---------------------------- | | boardId | Integer | The id of the board to fetch | -#### Response +##### Response ```json [ @@ -507,17 +510,17 @@ The board list endpoint supports setting an `If-Modified-Since` header to limit ] ``` -##### 200 Success +###### 200 Success -### GET /boards/{boardId}/stacks/archived - Get list of archived stacks +#### GET /boards/{boardId}/stacks/archived - Get list of archived stacks -#### Request parameters +##### Request parameters | Parameter | Type | Description | | --------- | ------- | ---------------------------- | | boardId | Integer | The id of the board to fetch | -#### Response +##### Response ```json [ @@ -533,78 +536,78 @@ The board list endpoint supports setting an `If-Modified-Since` header to limit ] ``` -##### 200 Success +###### 200 Success -### GET /boards/{boardId}/stacks/{stackId} - Get stack details +#### GET /boards/{boardId}/stacks/{stackId} - Get stack details -#### Request parameters +##### Request parameters | Parameter | Type | Description | | --------- | ------- | ---------------------------------------- | | boardId | Integer | The id of the board the stack belongs to | | stackId | Integer | The id of the stack | -#### Response +##### Response -##### 200 Success +###### 200 Success -### POST /boards/{boardId}/stacks - Create a new stack +#### POST /boards/{boardId}/stacks - Create a new stack -#### Request body +##### Request body | Parameter | Type | Description | | --------- | ------- | ---------------------------------------------------- | | title | String | The title of the new stack, maximum length is limited to 100 characters | | order | Integer | Order for sorting the stacks | -#### Request parameters +##### Request parameters | Parameter | Type | Description | | --------- | ------- | ---------------------------- | | boardId | Integer | The id of the board to fetch | -#### Response +##### Response -##### 200 Success +###### 200 Success -### PUT /boards/{boardId}/stacks/{stackId} - Update stack details +#### PUT /boards/{boardId}/stacks/{stackId} - Update stack details -#### Request parameters +##### Request parameters | Parameter | Type | Description | | --------- | ------- | ---------------------------------------- | | boardId | Integer | The id of the board the stack belongs to | | stackId | Integer | The id of the stack | -#### Request body +##### Request body | Parameter | Type | Description | | --------- | ------- | ---------------------------------------------------- | | title | String | The title of the stack, maximum length is limited to 100 characters | | order | Integer | Order for sorting the stacks | -#### Response +##### Response -##### 200 Success +###### 200 Success -### DELETE /boards/{boardId}/stacks/{stackId} - Delete a stack +#### DELETE /boards/{boardId}/stacks/{stackId} - Delete a stack -#### Request parameters +##### Request parameters | Parameter | Type | Description | | --------- | ------- | ---------------------------------------- | | boardId | Integer | The id of the board the stack belongs to | | stackId | Integer | The id of the stack | -#### Response +##### Response -##### 200 Success +###### 200 Success -## Cards +### Cards -### GET /boards/{boardId}/stacks/{stackId}/cards/{cardId} - Get card details +#### GET /boards/{boardId}/stacks/{stackId}/cards/{cardId} - Get card details -#### Request parameters +##### Request parameters | Parameter | Type | Description | | --------- | ------- | --------------------------------------- | @@ -612,20 +615,20 @@ The board list endpoint supports setting an `If-Modified-Since` header to limit | stackId | Integer | The id of the stack the card belongs to | | cardId | Integer | The id of the card | -#### Response +##### Response -##### 200 Success +###### 200 Success -### POST /boards/{boardId}/stacks/{stackId}/cards - Create a new card +#### POST /boards/{boardId}/stacks/{stackId}/cards - Create a new card -#### Request parameters +##### Request parameters | Parameter | Type | Description | | --------- | ------- | --------------------------------------- | | boardId | Integer | The id of the board the card belongs to | | stackId | Integer | The id of the stack the card belongs to | -#### Request body +##### Request body | Parameter | Type | Description | | --------- | ------- | ---------------------------------------------------- | @@ -635,7 +638,7 @@ The board list endpoint supports setting an `If-Modified-Since` header to limit | description | String | _(optional)_ The markdown description of the card | | duedate | timestamp | _(optional)_ The duedate of the card or null | -#### Response +##### Response ```json { @@ -661,11 +664,11 @@ The board list endpoint supports setting an `If-Modified-Since` header to limit } ``` -##### 200 Success +###### 200 Success -### PUT /boards/{boardId}/stacks/{stackId}/cards/{cardId} - Update card details +#### PUT /boards/{boardId}/stacks/{stackId}/cards/{cardId} - Update card details -#### Request parameters +##### Request parameters | Parameter | Type | Description | | --------- | ------- | --------------------------------------- | @@ -673,7 +676,7 @@ The board list endpoint supports setting an `If-Modified-Since` header to limit | stackId | Integer | The id of the stack the card belongs to | | cardId | Integer | The id of the card | -#### Request data +##### Request data | Parameter | Type | Description | |-------------|-----------------|-----------------------------------------------------------------------------------------------------| @@ -700,13 +703,13 @@ The board list endpoint supports setting an `If-Modified-Since` header to limit } ``` -#### Response +##### Response -##### 200 Success +###### 200 Success -### DELETE /boards/{boardId}/stacks/{stackId}/cards/{cardId} - Delete a card +#### DELETE /boards/{boardId}/stacks/{stackId}/cards/{cardId} - Delete a card -#### Request parameters +##### Request parameters | Parameter | Type | Description | | --------- | ------- | --------------------------------------- | @@ -714,13 +717,13 @@ The board list endpoint supports setting an `If-Modified-Since` header to limit | stackId | Integer | The id of the stack the card belongs to | | cardId | Integer | The id of the card | -#### Response +##### Response -##### 200 Success +###### 200 Success -### PUT /boards/{boardId}/stacks/{stackId}/cards/{cardId}/assignLabel - Assign a label to a card +#### PUT /boards/{boardId}/stacks/{stackId}/cards/{cardId}/assignLabel - Assign a label to a card -#### Request parameters +##### Request parameters | Parameter | Type | Description | | --------- | ------- | --------------------------------------- | @@ -728,18 +731,18 @@ The board list endpoint supports setting an `If-Modified-Since` header to limit | stackId | Integer | The id of the stack the card belongs to | | cardId | Integer | The id of the card | -#### Request data +##### Request data | Parameter | Type | Description | | --------- | ------- | --------------------------------------- | | labelId | Integer | The label id to assign to the card | -#### Response +##### Response -##### 200 Success +###### 200 Success -### PUT /boards/{boardId}/stacks/{stackId}/cards/{cardId}/removeLabel - Remove a label to a card +#### PUT /boards/{boardId}/stacks/{stackId}/cards/{cardId}/removeLabel - Remove a label to a card -#### Request parameters +##### Request parameters | Parameter | Type | Description | | --------- | ------- | --------------------------------------- | @@ -747,19 +750,19 @@ The board list endpoint supports setting an `If-Modified-Since` header to limit | stackId | Integer | The id of the stack the card belongs to | | cardId | Integer | The id of the card | -#### Request data +##### Request data | Parameter | Type | Description | | --------- | ------- | --------------------------------------- | | labelId | Integer | The label id to remove to the card | -#### Response +##### Response -##### 200 Success +###### 200 Success -### PUT /boards/{boardId}/stacks/{stackId}/cards/{cardId}/assignUser - Assign a user to a card +#### PUT /boards/{boardId}/stacks/{stackId}/cards/{cardId}/assignUser - Assign a user to a card -#### Request parameters +##### Request parameters | Parameter | Type | Description | | --------- | ------- | --------------------------------------- | @@ -767,15 +770,15 @@ The board list endpoint supports setting an `If-Modified-Since` header to limit | stackId | Integer | The id of the stack the card belongs to | | cardId | Integer | The id of the card | -#### Request data +##### Request data | Parameter | Type | Description | | --------- | ------- | --------------------------------------- | | userId | String | The user id to assign to the card | -#### Response +##### Response -##### 200 Success +###### 200 Success ```json { @@ -789,7 +792,7 @@ The board list endpoint supports setting an `If-Modified-Since` header to limit } ``` -##### 400 Bad request +###### 400 Bad request ```json { @@ -804,9 +807,9 @@ The request can fail with a bad request response for the following reasons: - The user is not part of the board -### PUT /boards/{boardId}/stacks/{stackId}/cards/{cardId}/unassignUser - Unassign a user from a card +#### PUT /boards/{boardId}/stacks/{stackId}/cards/{cardId}/unassignUser - Unassign a user from a card -#### Request parameters +##### Request parameters | Parameter | Type | Description | | --------- | ------- | --------------------------------------- | @@ -814,19 +817,19 @@ The request can fail with a bad request response for the following reasons: | stackId | Integer | The id of the stack the card belongs to | | cardId | Integer | The id of the card | -#### Request data +##### Request data | Parameter | Type | Description | | --------- | ------- | --------------------------------------- | | userId | String | The user id to unassign from the card | -#### Response +##### Response -##### 200 Success +###### 200 Success -### PUT /boards/{boardId}/stacks/{stackId}/cards/{cardId}/reorder - Change the sorting order of a card +#### PUT /boards/{boardId}/stacks/{stackId}/cards/{cardId}/reorder - Change the sorting order of a card -#### Request parameters +##### Request parameters | Parameter | Type | Description | | --------- | ------- | --------------------------------------- | @@ -834,7 +837,7 @@ The request can fail with a bad request response for the following reasons: | stackId | Integer | The id of the stack the card belongs to | | cardId | Integer | The id of the card | -#### Request data +##### Request data | Parameter | Type | Description | | --------- | ------- | ----------------------------------------------------------- | @@ -842,24 +845,24 @@ The request can fail with a bad request response for the following reasons: | stackId | Integer | The id of the stack where the card should be moved to | -#### Response +##### Response -##### 200 Success +###### 200 Success -## Labels +### Labels -### GET /boards/{boardId}/labels/{labelId} - Get label details +#### GET /boards/{boardId}/labels/{labelId} - Get label details -#### Request parameters +##### Request parameters | Parameter | Type | Description | | --------- | ------- | ---------------------------------------- | | boardId | Integer | The id of the board the label belongs to | | labelId | Integer | The id of the label | -#### Response +##### Response -##### 200 Success +###### 200 Success ```json { @@ -871,15 +874,15 @@ The request can fail with a bad request response for the following reasons: } ``` -### POST /boards/{boardId}/labels - Create a new label +#### POST /boards/{boardId}/labels - Create a new label -#### Request parameters +##### Request parameters | Parameter | Type | Description | | --------- | ------- | ---------------------------------------- | | boardId | Integer | The id of the board the label belongs to | -#### Request data +##### Request data ```json { @@ -888,13 +891,13 @@ The request can fail with a bad request response for the following reasons: } ``` -#### Response +##### Response -##### 200 Success +###### 200 Success -### PUT /boards/{boardId}/labels/{labelId} - Update label details +#### PUT /boards/{boardId}/labels/{labelId} - Update label details -#### Request parameters +##### Request parameters | Parameter | Type | Description | | --------- | ------- | ---------------------------------------- | @@ -902,7 +905,7 @@ The request can fail with a bad request response for the following reasons: | labelId | Integer | The id of the label | -#### Request data +##### Request data ```json { @@ -911,28 +914,28 @@ The request can fail with a bad request response for the following reasons: } ``` -#### Response +##### Response -##### 200 Success +###### 200 Success -### DELETE /boards/{boardId}/labels/{labelId} - Delete a label +#### DELETE /boards/{boardId}/labels/{labelId} - Delete a label -#### Request parameters +##### Request parameters | Parameter | Type | Description | | --------- | ------- | ---------------------------------------- | | boardId | Integer | The id of the board the label belongs to | | labelId | Integer | The id of the label | -#### Response +##### Response -##### 200 Success +###### 200 Success -## Attachments +### Attachments -### GET /boards/{boardId}/stacks/{stackId}/cards/{cardId}/attachments - Get a list of attachments +#### GET /boards/{boardId}/stacks/{stackId}/cards/{cardId}/attachments - Get a list of attachments -#### Request parameters +##### Request parameters | Parameter | Type | Description | | --------- | ------- | --------------------------------------- | @@ -940,9 +943,9 @@ The request can fail with a bad request response for the following reasons: | stackId | Integer | The id of the stack the card belongs to | | cardId | Integer | The id of the card | -#### Response +##### Response -##### 200 Success +###### 200 Success ```json [ @@ -970,9 +973,9 @@ The request can fail with a bad request response for the following reasons: ``` -### GET /boards/{boardId}/stacks/{stackId}/cards/{cardId}/attachments/{attachmentId} - Get the attachment file +#### GET /boards/{boardId}/stacks/{stackId}/cards/{cardId}/attachments/{attachmentId} - Get the attachment file -#### Request parameters +##### Request parameters | Parameter | Type | Description | | ------------ | ------- | --------------------------------------------- | @@ -981,13 +984,13 @@ The request can fail with a bad request response for the following reasons: | cardId | Integer | The id of the card the attachment belongs to | | attachmentId | Integer | The id of the attachment | -#### Response +##### Response -##### 200 Success +###### 200 Success -### POST /boards/{boardId}/stacks/{stackId}/cards/{cardId}/attachments - Upload an attachment +#### POST /boards/{boardId}/stacks/{stackId}/cards/{cardId}/attachments - Upload an attachment -#### Request parameters +##### Request parameters | Parameter | Type | Description | | --------- | ------- | --------------------------------------------- | @@ -995,7 +998,7 @@ The request can fail with a bad request response for the following reasons: | stackId | Integer | The id of the stack the attachment belongs to | | cardId | Integer | The id of the card the attachment belongs to | -#### Request data +##### Request data | Parameter | Type | Description | | --------- | ------- | --------------------------------------------- | @@ -1005,13 +1008,13 @@ The request can fail with a bad request response for the following reasons: - Prior to Deck version v1.3.0 (API v1.0), attachments were stored within deck. For this type of attachments `deck_file` was used as the default type of attachments - Starting with Deck version 1.3.0 (API v1.1) files are stored within the users regular Nextcloud files and the type `file` has been introduced for that -#### Response +##### Response -##### 200 Success +###### 200 Success -### PUT /boards/{boardId}/stacks/{stackId}/cards/{cardId}/attachments/{attachmentId} - Update an attachment +#### PUT /boards/{boardId}/stacks/{stackId}/cards/{cardId}/attachments/{attachmentId} - Update an attachment -#### Request parameters +##### Request parameters | Parameter | Type | Description | | ------------ | ------- | --------------------------------------------- | @@ -1020,7 +1023,7 @@ The request can fail with a bad request response for the following reasons: | cardId | Integer | The id of the card the attachment belongs to | | attachmentId | Integer | The id of the attachment | -#### Request data +##### Request data | Parameter | Type | Description | | --------- | ------- | --------------------------------------------- | @@ -1029,14 +1032,14 @@ The request can fail with a bad request response for the following reasons: For now only `deck_file` is supported as an attachment type. -#### Response +##### Response -##### 200 Success +###### 200 Success -### DELETE /boards/{boardId}/stacks/{stackId}/cards/{cardId}/attachments/{attachmentId} - Delete an attachment +#### DELETE /boards/{boardId}/stacks/{stackId}/cards/{cardId}/attachments/{attachmentId} - Delete an attachment -#### Request parameters +##### Request parameters | Parameter | Type | Description | | ------------ | ------- | --------------------------------------------- | @@ -1045,13 +1048,13 @@ For now only `deck_file` is supported as an attachment type. | cardId | Integer | The id of the card the attachment belongs to | | attachmentId | Integer | The id of the attachment | -#### Response +##### Response -##### 200 Success +###### 200 Success -### PUT /boards/{boardId}/stacks/{stackId}/cards/{cardId}/attachments/{attachmentId}/restore - Resore a deleted attachment +#### PUT /boards/{boardId}/stacks/{stackId}/cards/{cardId}/attachments/{attachmentId}/restore - Resore a deleted attachment -#### Request parameters +##### Request parameters | Parameter | Type | Description | | ------------ | ------- | --------------------------------------------- | @@ -1060,19 +1063,19 @@ For now only `deck_file` is supported as an attachment type. | cardId | Integer | The id of the card the attachment belongs to | | attachmentId | Integer | The id of the attachment | -#### Response +##### Response -##### 200 Success +###### 200 Success -### GET /boards/import/getSystems - Import a board +#### GET /boards/import/getSystems - Import a board -#### Request parameters +##### Request parameters | Parameter | Type | Description | | ------------ | ------- | --------------------------------------------- | | system | Integer | The system name. Example: trello | -#### Response +##### Response Make a request to see the json schema of system @@ -1081,11 +1084,11 @@ Make a request to see the json schema of system } ``` -### GET /boards/import/config/system/{schema} - Import a board +#### GET /boards/import/config/system/{schema} - Import a board -#### Request parameters +##### Request parameters -#### Response +##### Response ```json [ @@ -1093,9 +1096,9 @@ Make a request to see the json schema of system ] ``` -### POST /boards/import - Import a board +#### POST /boards/import - Import a board -#### Request parameters +##### Request parameters | Parameter | Type | Description | | ------------ | ------- | --------------------------------------------- | @@ -1103,22 +1106,22 @@ Make a request to see the json schema of system | config | Object | The config object (JSON) | | data | Object | The data object to import (JSON) | -#### Response +##### Response -##### 200 Success +###### 200 Success -# OCS API +## OCS API The following endpoints are available through the Nextcloud OCS endpoint, which is available at `/ocs/v2.php/apps/deck/api/v1.0/`. This has the benefit that both the web UI as well as external integrations can use the same API. -## Config +### Config Deck stores user and app configuration values globally and per board. The GET endpoint allows to fetch the current global configuration while board settings will be exposed through the board element on the regular API endpoints. -### GET /api/v1.0/config - Fetch app configuration values +#### GET /api/v1.0/config - Fetch app configuration values -#### Response +##### Response | Config key | Description | | --- | --- | @@ -1151,10 +1154,10 @@ Deck stores user and app configuration values globally and per board. The GET en ``` -### POST /api/v1.0/config/{id}/{key} - Set a config value +#### POST /api/v1.0/config/{id}/{key} - Set a config value -#### Request parameters +##### Request parameters | Parameter | Type | Description | | --------- | ------- | --------------------------------------- | @@ -1162,7 +1165,7 @@ Deck stores user and app configuration values globally and per board. The GET en | key | String | The config key to set, prefixed with `board:{boardId}:` for board specific settings | | value | String | The value that should be stored for the config key | -##### Board configuration +###### Board configuration | Key | Value | | --- | ----- | @@ -1171,7 +1174,7 @@ Deck stores user and app configuration values globally and per board. The GET en | cardDetailsInModal | Boolean | | cardIdBadge | Boolean | -#### Example request +##### Example request ``` curl -X POST 'https://admin:admin@nextcloud.local/ocs/v2.php/apps/deck/api/v1.0/config/calendar' -H 'Accept: application/json' -H "Content-Type: application/json" -H 'OCS-APIRequest: true' --data-raw '{"value":false}' @@ -1189,11 +1192,11 @@ curl -X POST 'https://admin:admin@nextcloud.local/ocs/v2.php/apps/deck/api/v1.0/ ``` -## Comments +### Comments -### GET /cards/{cardId}/comments - List comments +#### GET /cards/{cardId}/comments - List comments -#### Request parameters +##### Request parameters string $cardId, int $limit = 20, int $offset = 0 @@ -1208,11 +1211,11 @@ curl 'https://admin:admin@nextcloud/ocs/v2.php/apps/deck/api/v1.0/cards/12/comme -H 'Accept: application/json' -H 'OCS-APIRequest: true' ``` -#### Response +##### Response A list of comments will be provided under the `ocs.data` key. If no or no more comments are available the list will be empty. -##### 200 Success +###### 200 Success ``` { @@ -1284,9 +1287,9 @@ In case a comment is marked as a reply to another comment object, the parent com ``` -### POST /cards/{cardId}/comments - Create a new comment +#### POST /cards/{cardId}/comments - Create a new comment -#### Request parameters +##### Request parameters | Parameter | Type | Description | | --------- | ------- | --------------------------------------- | @@ -1303,11 +1306,11 @@ curl -X POST 'https://admin:admin@nextcloud/ocs/v2.php/apps/deck/api/v1.0/cards/ --data '{"message":"My message to @bob","parentId":null}' ``` -#### Response +##### Response A list of comments will be provided under the `ocs.data` key. If no or no more comments are available the list will be empty. -##### 200 Success +###### 200 Success ``` { @@ -1337,20 +1340,20 @@ A list of comments will be provided under the `ocs.data` key. If no or no more c } ``` -##### 400 Bad request +###### 400 Bad request A bad request response is returned if invalid input values are provided. The response message will contain details about which part was not valid. -##### 404 Not found +###### 404 Not found A not found response might be returned if: - The card for the given cardId could not be found - The parent comment could not be found -### PUT /cards/{cardId}/comments/{commentId} - Update a comment +#### PUT /cards/{cardId}/comments/{commentId} - Update a comment -#### Request parameters +##### Request parameters | Parameter | Type | Description | | --------- | ------- | --------------------------------------- | @@ -1369,11 +1372,11 @@ curl -X POST 'https://admin:admin@nextcloud/ocs/v2.php/apps/deck/api/v1.0/cards/ --data '{"message":"My message"}' ``` -#### Response +##### Response A list of comments will be provided under the `ocs.data` key. If no or no more comments are available the list will be empty. -##### 200 Success +###### 200 Success ``` { @@ -1397,19 +1400,19 @@ A list of comments will be provided under the `ocs.data` key. If no or no more c } ``` -##### 400 Bad request +###### 400 Bad request A bad request response is returned if invalid input values are provided. The response message will contain details about which part was not valid. -##### 404 Not found +###### 404 Not found A not found response might be returned if: - The card for the given cardId could not be found - The comment could not be found -### DELETE /cards/{cardId}/comments/{commentId} - Delete a comment +#### DELETE /cards/{cardId}/comments/{commentId} - Delete a comment -#### Request parameters +##### Request parameters | Parameter | Type | Description | | --------- | ------- | --------------------------------------- | @@ -1424,11 +1427,11 @@ curl -X DELETE 'https://admin:admin@nextcloud/ocs/v2.php/apps/deck/api/v1.0/card -H 'Content-Type: application/json;charset=utf-8' ``` -#### Response +##### Response A list of comments will be provided under the `ocs.data` key. If no or no more comments are available the list will be empty. -##### 200 Success +###### 200 Success ``` { @@ -1443,22 +1446,22 @@ A list of comments will be provided under the `ocs.data` key. If no or no more c } ``` -##### 400 Bad request +###### 400 Bad request A bad request response is returned if invalid input values are provided. The response message will contain details about which part was not valid. -##### 404 Not found +###### 404 Not found A not found response might be returned if: - The card for the given cardId could not be found - The comment could not be found -## Sessions +### Sessions -### PUT /session/create - creates a new session +#### PUT /session/create - creates a new session -#### Request parameters +##### Request parameters | Parameter | Type | Description | | --------- | ------- | ---------------------------------------------------- | @@ -1471,9 +1474,9 @@ curl -X PUT 'https://admin:admin@nextcloud/ocs/v2.php/apps/deck/api/v1.0/session --data '{"boardId":1}' ``` -#### Response +##### Response -##### 200 Success +###### 200 Success ```json { @@ -1491,9 +1494,9 @@ curl -X PUT 'https://admin:admin@nextcloud/ocs/v2.php/apps/deck/api/v1.0/session ``` -### POST /session/sync - notifies the server, that the session is still open +#### POST /session/sync - notifies the server, that the session is still open -#### Request body +##### Request body | Parameter | Type | Description | | --------- | ------- | ---------------------------------------------------- | @@ -1508,9 +1511,9 @@ curl -X POST 'https://admin:admin@nextcloud/ocs/v2.php/apps/deck/api/v1.0/sessio --data '{"boardId":1, "token":"X3DyyoFslArF0t0NBZXzZXzcy8feoX/OEytSNXZtPg9TpUgO5wrkJ38IW3T/FfpV"}' ``` -#### Response +##### Response -##### 200 Success +###### 200 Success ```json { "ocs": { @@ -1524,13 +1527,13 @@ curl -X POST 'https://admin:admin@nextcloud/ocs/v2.php/apps/deck/api/v1.0/sessio } ``` -##### 404 Not Found +###### 404 Not Found the provided token is invalid or expired -### POST /session/close - closes the session +#### POST /session/close - closes the session -#### Request body +##### Request body | Parameter | Type | Description | | --------- | ------- | ---------------------------------------------------- | @@ -1544,9 +1547,9 @@ curl -X POST 'https://admin:admin@nextcloud/ocs/v2.php/apps/deck/api/v1.0/sessio --data '{"boardId":1, "token":"X3DyyoFslArF0t0NBZXzZXzcy8feoX/OEytSNXZtPg9TpUgO5wrkJ38IW3T/FfpV"}' ``` -#### Response +##### Response -##### 200 Success +###### 200 Success ```json { "ocs": { diff --git a/docs/Markdown.md b/docs/Markdown.md index 7c748fb292..46e74bd7be 100644 --- a/docs/Markdown.md +++ b/docs/Markdown.md @@ -2,6 +2,8 @@ - SPDX-FileCopyrightText: 2018 Nextcloud GmbH and Nextcloud contributors - SPDX-License-Identifier: AGPL-3.0-or-later --> +# Markdown composing + ## What is Markdown The [wikipedia markdown entry](https://en.wikipedia.org/wiki/Markdown) introduced markdown as : @@ -14,7 +16,7 @@ The Deck application plugin uses the [markdown-it](https://github.com/markdown-i ## Supported Markdown Markdown comes in many flavors. The best way to learn markdown and understand how to use it, is simply to [try it](https://markdown-it.github.io) on the original script official playground. -That same link offers also a comprehensive list of what is supported, and what is not - rendering it unnecessary to duplicate that content in here. +That same link offers also a comprehensive list of what is supported, and what is not - rendering it unnecessary to duplicate that content in here. [CommonMark Markdown Reference](http://commonmark.org/help/) diff --git a/docs/User_documentation_en.md b/docs/User_documentation_en.md index 1f604cb4a4..e17c6697d7 100644 --- a/docs/User_documentation_en.md +++ b/docs/User_documentation_en.md @@ -2,6 +2,8 @@ - SPDX-FileCopyrightText: 2019 Nextcloud GmbH and Nextcloud contributors - SPDX-License-Identifier: AGPL-3.0-or-later --> +# User Documentation + ## Introduction ### What about Deck ? diff --git a/mkdocs.yml b/mkdocs.yml index 046067cd85..bab07d06ce 100644 --- a/mkdocs.yml +++ b/mkdocs.yml @@ -4,8 +4,8 @@ site_name: Nextcloud Deck theme: name: readthedocs extra_css: [extra.css] -pages: - - Home: index.md +nav: + - Deck: index.md - User documentation: User_documentation_en.md - Markdown composing: Markdown.md - API documentation: From e5b8aa50a3ad2b35821844af77db501a92a1ffb5 Mon Sep 17 00:00:00 2001 From: Viktor Diezel Date: Wed, 6 Aug 2025 21:18:29 +0200 Subject: [PATCH 02/30] docs: make sidebar entries readable Signed-off-by: Viktor Diezel --- docs/extra.css | 13 +++++++++++-- 1 file changed, 11 insertions(+), 2 deletions(-) diff --git a/docs/extra.css b/docs/extra.css index dbfe1dd58e..be6cc3def2 100644 --- a/docs/extra.css +++ b/docs/extra.css @@ -2,6 +2,15 @@ * SPDX-FileCopyrightText: 2018 Nextcloud GmbH and Nextcloud contributors * SPDX-License-Identifier: AGPL-3.0-or-later */ -.subnav ul { - padding-left: 20px; + +.wy-menu li a { + font-size: 1rem; } + +.wy-menu-vertical li.toctree-l2.current li.toctree-l3>a { + padding-inline-start: 3em; +} + +.wy-menu-vertical li.toctree-l2 li.toctree-l3.current li.toctree-l4>a { + padding-inline-start: 3.5em; +} \ No newline at end of file From ba88f385387e678bd339e8b8a92d4bf635f4dcab Mon Sep 17 00:00:00 2001 From: Viktor Diezel Date: Wed, 6 Aug 2025 21:31:15 +0200 Subject: [PATCH 03/30] docs: fixes a series of types and bad markdown formatting in API.md Signed-off-by: Viktor Diezel --- docs/API.md | 27 ++++++++++++++------------- 1 file changed, 14 insertions(+), 13 deletions(-) diff --git a/docs/API.md b/docs/API.md index 6325f97fb7..32b8fb1ac0 100644 --- a/docs/API.md +++ b/docs/API.md @@ -115,14 +115,14 @@ This API version has become available with **Deck 1.3.0**. - The API will now return a 400 Bad request response if the length limitation of a board, stack or card title is exceeded - The attachments API endpoints will return other attachment types than deck_file - Prior to Deck version v1.3.0 (API v1.0), attachments were stored within deck. For this type of attachments `deck_file` was used as the default type of attachments - - Starting with Deck version 1.3.0 (API v1.1) files are stored within the users regular Nextcloud files and the type `file` has been introduced for that + - Starting with Deck version 1.3.0 (API v1.1) files are stored within the user's regular Nextcloud files and the type `file` has been introduced for that ### API version 1.2 (unreleased) - Endpoints for the new import functionality have been added: - - [GET /boards/import/getSystems - Import a board](#get-boardsimportgetsystems-import-a-board) - - [GET /boards/import/config/system/{schema} - Import a board](#get-boardsimportconfigsystemschema-import-a-board) - - [POST /boards/import - Import a board](#post-boardsimport-import-a-board) + - [GET /boards/import/getSystems - Import a board](#get-boardsimportgetsystems-import-a-board) + - [GET /boards/import/config/system/{schema} - Import a board](#get-boardsimportconfigsystemschema-import-a-board) + - [POST /boards/import - Import a board](#post-boardsimport-import-a-board) - The `done` property was added to cards ## Endpoints @@ -255,7 +255,7 @@ Returns an array of board items ###### 403 Forbidden -A 403 response might be returned if the users ability to create new boards has been disabled by the administrator. For checking this before, see the `canCreateBoards` value in the [Nextcloud capabilties](./API-Nextcloud.md). +A 403 response might be returned if the user's ability to create new boards has been disabled by the administrator. For checking this before, see the `canCreateBoards` value in the [Nextcloud capabilties](./API-Nextcloud.md). #### GET /boards/{boardId} - Get board details @@ -740,7 +740,7 @@ The board list endpoint supports setting an `If-Modified-Since` header to limit ###### 200 Success -#### PUT /boards/{boardId}/stacks/{stackId}/cards/{cardId}/removeLabel - Remove a label to a card +#### PUT /boards/{boardId}/stacks/{stackId}/cards/{cardId}/removeLabel - Remove a label from a card ##### Request parameters @@ -802,6 +802,7 @@ The board list endpoint supports setting an `If-Modified-Since` header to limit ``` The request can fail with a bad request response for the following reasons: + - Missing or wrongly formatted request parameters - The user is already assigned to the card - The user is not part of the board @@ -1006,7 +1007,7 @@ The request can fail with a bad request response for the following reasons: | file | Binary | File data to add as an attachment | - Prior to Deck version v1.3.0 (API v1.0), attachments were stored within deck. For this type of attachments `deck_file` was used as the default type of attachments -- Starting with Deck version 1.3.0 (API v1.1) files are stored within the users regular Nextcloud files and the type `file` has been introduced for that +- Starting with Deck version 1.3.0 (API v1.1) files are stored within the user's regular Nextcloud files and the type `file` has been introduced for that ##### Response @@ -1052,7 +1053,7 @@ For now only `deck_file` is supported as an attachment type. ###### 200 Success -#### PUT /boards/{boardId}/stacks/{stackId}/cards/{cardId}/attachments/{attachmentId}/restore - Resore a deleted attachment +#### PUT /boards/{boardId}/stacks/{stackId}/cards/{cardId}/attachments/{attachmentId}/restore - Restore a deleted attachment ##### Request parameters @@ -1198,8 +1199,6 @@ curl -X POST 'https://admin:admin@nextcloud.local/ocs/v2.php/apps/deck/api/v1.0/ ##### Request parameters -string $cardId, int $limit = 20, int $offset = 0 - | Parameter | Type | Description | | --------- | ------- | --------------------------------------- | | cardId | Integer | The id of the card | @@ -1347,6 +1346,7 @@ A bad request response is returned if invalid input values are provided. The res ###### 404 Not found A not found response might be returned if: + - The card for the given cardId could not be found - The parent comment could not be found @@ -1366,7 +1366,7 @@ Mentions will be parsed by the server. The server will return a list of mentions Updating comments is limited to the current user being the same as the comment author specified in the `actorId` of the comment. ``` -curl -X POST 'https://admin:admin@nextcloud/ocs/v2.php/apps/deck/api/v1.0/cards/12/comments' \ +curl -X PUT 'https://admin:admin@nextcloud/ocs/v2.php/apps/deck/api/v1.0/cards/12/comments/123' \ -H 'Accept: application/json' -H 'OCS-APIRequest: true' -H 'Content-Type: application/json;charset=utf-8' --data '{"message":"My message"}' @@ -1407,6 +1407,7 @@ A bad request response is returned if invalid input values are provided. The res ###### 404 Not found A not found response might be returned if: + - The card for the given cardId could not be found - The comment could not be found @@ -1422,7 +1423,7 @@ A not found response might be returned if: Deleting comments is limited to the current user being the same as the comment author specified in the `actorId` of the comment. ``` -curl -X DELETE 'https://admin:admin@nextcloud/ocs/v2.php/apps/deck/api/v1.0/cards/12/comments' \ +curl -X DELETE 'https://admin:admin@nextcloud/ocs/v2.php/apps/deck/api/v1.0/cards/12/comments/123' \ -H 'Accept: application/json' -H 'OCS-APIRequest: true' -H 'Content-Type: application/json;charset=utf-8' ``` @@ -1453,10 +1454,10 @@ A bad request response is returned if invalid input values are provided. The res ###### 404 Not found A not found response might be returned if: + - The card for the given cardId could not be found - The comment could not be found - ### Sessions #### PUT /session/create - creates a new session From 49a4a55c9b48e48a3ae1fca76de19ce26d9f17f5 Mon Sep 17 00:00:00 2001 From: Viktor Diezel Date: Wed, 6 Aug 2025 21:45:41 +0200 Subject: [PATCH 04/30] docs: separate URL and API title for better navigation entries Signed-off-by: Viktor Diezel --- docs/API.md | 147 ++++++++++++++++++++++++++++++++++------------------ 1 file changed, 98 insertions(+), 49 deletions(-) diff --git a/docs/API.md b/docs/API.md index 32b8fb1ac0..0f75df6ff1 100644 --- a/docs/API.md +++ b/docs/API.md @@ -129,7 +129,8 @@ This API version has become available with **Deck 1.3.0**. ### Boards -#### GET /boards - Get a list of boards +#### Get a list of boards +`GET /boards` ##### Headers @@ -179,7 +180,8 @@ Returns an array of board items ] ``` -#### POST /boards - Create a new board +#### Create a new board +`POST /boards` ##### Request body @@ -257,7 +259,8 @@ Returns an array of board items A 403 response might be returned if the user's ability to create new boards has been disabled by the administrator. For checking this before, see the `canCreateBoards` value in the [Nextcloud capabilties](./API-Nextcloud.md). -#### GET /boards/{boardId} - Get board details +#### Get board details +`GET /boards/{boardId}` ##### Request parameters @@ -328,7 +331,8 @@ A 403 response might be returned if the user's ability to create new boards has } ``` -#### PUT /boards/{boardId} - Update board details +#### Update board details +`PUT /boards/{boardId}` ##### Request body @@ -350,7 +354,8 @@ A 403 response might be returned if the user's ability to create new boards has ###### 200 Success -#### PUT /boards/{boardId}/stacks/{stackId}/cards/{cardId}/archive - Archive a card +#### Archive a card +`PUT /boards/{boardId}/stacks/{stackId}/cards/{cardId}/archive` ##### Request parameters @@ -364,7 +369,8 @@ A 403 response might be returned if the user's ability to create new boards has ###### 200 Success -#### PUT /boards/{boardId}/stacks/{stackId}/cards/{cardId}/unarchive - Unarchive a card +#### Unarchive a card +`PUT /boards/{boardId}/stacks/{stackId}/cards/{cardId}/unarchive` ##### Request parameters @@ -378,7 +384,8 @@ A 403 response might be returned if the user's ability to create new boards has ###### 200 Success -#### DELETE /boards/{boardId} - Delete a board +#### Delete a board +`DELETE /boards/{boardId}` ##### Request parameters @@ -390,7 +397,8 @@ A 403 response might be returned if the user's ability to create new boards has ###### 200 Success -#### POST /boards/{boardId}/undo_delete - Restore a deleted board +#### Restore a deleted board +`POST /boards/{boardId}/undo_delete` ##### Request parameters @@ -402,7 +410,8 @@ A 403 response might be returned if the user's ability to create new boards has ###### 200 Success -#### POST /boards/{boardId}/acl - Add new acl rule +#### Add new acl rule +`POST /boards/{boardId}/acl` ##### Request body @@ -440,7 +449,8 @@ A 403 response might be returned if the user's ability to create new boards has }] ``` -#### PUT /boards/{boardId}/acl/{aclId} - Update an acl rule +#### Update an acl rule +`PUT /boards/{boardId}/acl/{aclId}` ##### Request parameters @@ -454,7 +464,8 @@ A 403 response might be returned if the user's ability to create new boards has ###### 200 Success -#### POST /boards/{boardId}/clone - Clone a board +#### Clone a board +`POST /boards/{boardId}/clone` Creates a copy of the board. @@ -473,7 +484,8 @@ Creates a copy of the board. ###### 200 Success -#### DELETE /boards/{boardId}/acl/{aclId} - Delete an acl rule +#### Delete an acl rule +`DELETE /boards/{boardId}/acl/{aclId}` ##### Response @@ -481,7 +493,8 @@ Creates a copy of the board. ### Stacks -#### GET /boards/{boardId}/stacks - Get stacks +#### Get stacks +`GET /boards/{boardId}/stacks` ##### Headers @@ -512,7 +525,8 @@ The board list endpoint supports setting an `If-Modified-Since` header to limit ###### 200 Success -#### GET /boards/{boardId}/stacks/archived - Get list of archived stacks +#### Get list of archived stacks +`GET /boards/{boardId}/stacks/archived` ##### Request parameters @@ -538,7 +552,8 @@ The board list endpoint supports setting an `If-Modified-Since` header to limit ###### 200 Success -#### GET /boards/{boardId}/stacks/{stackId} - Get stack details +#### Get stack details +`GET /boards/{boardId}/stacks/{stackId}` ##### Request parameters @@ -551,7 +566,8 @@ The board list endpoint supports setting an `If-Modified-Since` header to limit ###### 200 Success -#### POST /boards/{boardId}/stacks - Create a new stack +#### Create a new stack +`POST /boards/{boardId}/stacks` ##### Request body @@ -570,7 +586,8 @@ The board list endpoint supports setting an `If-Modified-Since` header to limit ###### 200 Success -#### PUT /boards/{boardId}/stacks/{stackId} - Update stack details +#### Update stack details +`PUT /boards/{boardId}/stacks/{stackId}` ##### Request parameters @@ -590,7 +607,8 @@ The board list endpoint supports setting an `If-Modified-Since` header to limit ###### 200 Success -#### DELETE /boards/{boardId}/stacks/{stackId} - Delete a stack +#### Delete a stack +`DELETE /boards/{boardId}/stacks/{stackId}` ##### Request parameters @@ -605,7 +623,8 @@ The board list endpoint supports setting an `If-Modified-Since` header to limit ### Cards -#### GET /boards/{boardId}/stacks/{stackId}/cards/{cardId} - Get card details +#### Get card details +`GET /boards/{boardId}/stacks/{stackId}/cards/{cardId}` ##### Request parameters @@ -619,7 +638,8 @@ The board list endpoint supports setting an `If-Modified-Since` header to limit ###### 200 Success -#### POST /boards/{boardId}/stacks/{stackId}/cards - Create a new card +#### Create a new card +`POST /boards/{boardId}/stacks/{stackId}/cards` ##### Request parameters @@ -666,7 +686,8 @@ The board list endpoint supports setting an `If-Modified-Since` header to limit ###### 200 Success -#### PUT /boards/{boardId}/stacks/{stackId}/cards/{cardId} - Update card details +#### Update card details +`PUT /boards/{boardId}/stacks/{stackId}/cards/{cardId}` ##### Request parameters @@ -707,7 +728,8 @@ The board list endpoint supports setting an `If-Modified-Since` header to limit ###### 200 Success -#### DELETE /boards/{boardId}/stacks/{stackId}/cards/{cardId} - Delete a card +#### Delete a card +`DELETE /boards/{boardId}/stacks/{stackId}/cards/{cardId}` ##### Request parameters @@ -721,7 +743,8 @@ The board list endpoint supports setting an `If-Modified-Since` header to limit ###### 200 Success -#### PUT /boards/{boardId}/stacks/{stackId}/cards/{cardId}/assignLabel - Assign a label to a card +#### Assign a label to a card +`PUT /boards/{boardId}/stacks/{stackId}/cards/{cardId}/assignLabel` ##### Request parameters @@ -740,7 +763,8 @@ The board list endpoint supports setting an `If-Modified-Since` header to limit ###### 200 Success -#### PUT /boards/{boardId}/stacks/{stackId}/cards/{cardId}/removeLabel - Remove a label from a card +#### Remove a label from a card +`PUT /boards/{boardId}/stacks/{stackId}/cards/{cardId}/removeLabel` ##### Request parameters @@ -760,7 +784,8 @@ The board list endpoint supports setting an `If-Modified-Since` header to limit ###### 200 Success -#### PUT /boards/{boardId}/stacks/{stackId}/cards/{cardId}/assignUser - Assign a user to a card +#### Assign a user to a card +`PUT /boards/{boardId}/stacks/{stackId}/cards/{cardId}/assignUser` ##### Request parameters @@ -808,7 +833,8 @@ The request can fail with a bad request response for the following reasons: - The user is not part of the board -#### PUT /boards/{boardId}/stacks/{stackId}/cards/{cardId}/unassignUser - Unassign a user from a card +#### Unassign a user from a card +`PUT /boards/{boardId}/stacks/{stackId}/cards/{cardId}/unassignUser` ##### Request parameters @@ -828,7 +854,8 @@ The request can fail with a bad request response for the following reasons: ###### 200 Success -#### PUT /boards/{boardId}/stacks/{stackId}/cards/{cardId}/reorder - Change the sorting order of a card +#### Change the sorting order of a card +`PUT /boards/{boardId}/stacks/{stackId}/cards/{cardId}/reorder` ##### Request parameters @@ -852,7 +879,8 @@ The request can fail with a bad request response for the following reasons: ### Labels -#### GET /boards/{boardId}/labels/{labelId} - Get label details +#### Get label details +`GET /boards/{boardId}/labels/{labelId}` ##### Request parameters @@ -875,7 +903,8 @@ The request can fail with a bad request response for the following reasons: } ``` -#### POST /boards/{boardId}/labels - Create a new label +#### Create a new label +`POST /boards/{boardId}/labels` ##### Request parameters @@ -896,7 +925,8 @@ The request can fail with a bad request response for the following reasons: ###### 200 Success -#### PUT /boards/{boardId}/labels/{labelId} - Update label details +#### Update label details +`PUT /boards/{boardId}/labels/{labelId}` ##### Request parameters @@ -919,7 +949,8 @@ The request can fail with a bad request response for the following reasons: ###### 200 Success -#### DELETE /boards/{boardId}/labels/{labelId} - Delete a label +#### Delete a label +`DELETE /boards/{boardId}/labels/{labelId}` ##### Request parameters @@ -934,7 +965,8 @@ The request can fail with a bad request response for the following reasons: ### Attachments -#### GET /boards/{boardId}/stacks/{stackId}/cards/{cardId}/attachments - Get a list of attachments +#### Get a list of attachments +`GET /boards/{boardId}/stacks/{stackId}/cards/{cardId}/attachments` ##### Request parameters @@ -974,7 +1006,8 @@ The request can fail with a bad request response for the following reasons: ``` -#### GET /boards/{boardId}/stacks/{stackId}/cards/{cardId}/attachments/{attachmentId} - Get the attachment file +#### Get the attachment file +`GET /boards/{boardId}/stacks/{stackId}/cards/{cardId}/attachments/{attachmentId}` ##### Request parameters @@ -989,7 +1022,8 @@ The request can fail with a bad request response for the following reasons: ###### 200 Success -#### POST /boards/{boardId}/stacks/{stackId}/cards/{cardId}/attachments - Upload an attachment +#### Upload an attachment +`POST /boards/{boardId}/stacks/{stackId}/cards/{cardId}/attachments` ##### Request parameters @@ -1013,7 +1047,8 @@ The request can fail with a bad request response for the following reasons: ###### 200 Success -#### PUT /boards/{boardId}/stacks/{stackId}/cards/{cardId}/attachments/{attachmentId} - Update an attachment +#### Update an attachment +`PUT /boards/{boardId}/stacks/{stackId}/cards/{cardId}/attachments/{attachmentId}` ##### Request parameters @@ -1037,7 +1072,8 @@ For now only `deck_file` is supported as an attachment type. ###### 200 Success -#### DELETE /boards/{boardId}/stacks/{stackId}/cards/{cardId}/attachments/{attachmentId} - Delete an attachment +#### Delete an attachment +`DELETE /boards/{boardId}/stacks/{stackId}/cards/{cardId}/attachments/{attachmentId}` ##### Request parameters @@ -1053,7 +1089,8 @@ For now only `deck_file` is supported as an attachment type. ###### 200 Success -#### PUT /boards/{boardId}/stacks/{stackId}/cards/{cardId}/attachments/{attachmentId}/restore - Restore a deleted attachment +#### Restore a deleted attachment +`PUT /boards/{boardId}/stacks/{stackId}/cards/{cardId}/attachments/{attachmentId}/restore` ##### Request parameters @@ -1068,7 +1105,8 @@ For now only `deck_file` is supported as an attachment type. ###### 200 Success -#### GET /boards/import/getSystems - Import a board +#### Import a board +`GET /boards/import/getSystems` ##### Request parameters @@ -1085,7 +1123,8 @@ Make a request to see the json schema of system } ``` -#### GET /boards/import/config/system/{schema} - Import a board +#### Import a board +`GET /boards/import/config/system/{schema}` ##### Request parameters @@ -1097,7 +1136,8 @@ Make a request to see the json schema of system ] ``` -#### POST /boards/import - Import a board +#### Import a board +`POST /boards/import` ##### Request parameters @@ -1120,7 +1160,8 @@ This has the benefit that both the web UI as well as external integrations can u Deck stores user and app configuration values globally and per board. The GET endpoint allows to fetch the current global configuration while board settings will be exposed through the board element on the regular API endpoints. -#### GET /api/v1.0/config - Fetch app configuration values +#### Fetch app configuration values +`GET /api/v1.0/config` ##### Response @@ -1155,7 +1196,8 @@ Deck stores user and app configuration values globally and per board. The GET en ``` -#### POST /api/v1.0/config/{id}/{key} - Set a config value +#### Set a config value +`POST /api/v1.0/config/{id}/{key}` ##### Request parameters @@ -1195,7 +1237,8 @@ curl -X POST 'https://admin:admin@nextcloud.local/ocs/v2.php/apps/deck/api/v1.0/ ### Comments -#### GET /cards/{cardId}/comments - List comments +#### List comments +`GET /cards/{cardId}/comments` ##### Request parameters @@ -1286,7 +1329,8 @@ In case a comment is marked as a reply to another comment object, the parent com ``` -#### POST /cards/{cardId}/comments - Create a new comment +#### Create a new comment +`POST /cards/{cardId}/comments` ##### Request parameters @@ -1351,7 +1395,8 @@ A not found response might be returned if: - The parent comment could not be found -#### PUT /cards/{cardId}/comments/{commentId} - Update a comment +#### Update a comment +`PUT /cards/{cardId}/comments/{commentId}` ##### Request parameters @@ -1411,7 +1456,8 @@ A not found response might be returned if: - The card for the given cardId could not be found - The comment could not be found -#### DELETE /cards/{cardId}/comments/{commentId} - Delete a comment +#### Delete a comment +`DELETE /cards/{cardId}/comments/{commentId}` ##### Request parameters @@ -1460,7 +1506,8 @@ A not found response might be returned if: ### Sessions -#### PUT /session/create - creates a new session +#### creates a new session +`PUT /session/create` ##### Request parameters @@ -1495,7 +1542,8 @@ curl -X PUT 'https://admin:admin@nextcloud/ocs/v2.php/apps/deck/api/v1.0/session ``` -#### POST /session/sync - notifies the server, that the session is still open +#### notifies the server, that the session is still open +`POST /session/sync` ##### Request body @@ -1532,7 +1580,8 @@ curl -X POST 'https://admin:admin@nextcloud/ocs/v2.php/apps/deck/api/v1.0/sessio the provided token is invalid or expired -#### POST /session/close - closes the session +#### closes the session +`POST /session/close` ##### Request body From bd95f3cbde14f57f1bd24c3545c8dffb6fccc7de Mon Sep 17 00:00:00 2001 From: Viktor Diezel Date: Wed, 6 Aug 2025 22:02:17 +0200 Subject: [PATCH 05/30] docs: Further fixes of order, missing request parameter and unification of names Signed-off-by: Viktor Diezel --- docs/API.md | 193 ++++++++++++++++++++++++++++++---------------------- 1 file changed, 112 insertions(+), 81 deletions(-) diff --git a/docs/API.md b/docs/API.md index 0f75df6ff1..8a88e9bde9 100644 --- a/docs/API.md +++ b/docs/API.md @@ -334,6 +334,12 @@ A 403 response might be returned if the user's ability to create new boards has #### Update board details `PUT /boards/{boardId}` +##### Request parameters + +| Parameter | Type | Description | +| --------- | ------ | ---------------------------------------------------- | +| boardId | Integer | The id of the board | + ##### Request body | Parameter | Type | Description | @@ -354,38 +360,21 @@ A 403 response might be returned if the user's ability to create new boards has ###### 200 Success -#### Archive a card -`PUT /boards/{boardId}/stacks/{stackId}/cards/{cardId}/archive` - -##### Request parameters - -| Parameter | Type | Description | -| --------- | ------- | --------------------------------------- | -| boardId | Integer | The id of the board the card belongs to | -| stackId | Integer | The id of the stack the card belongs to | -| cardId | Integer | The id of the card | - -##### Response - -###### 200 Success - -#### Unarchive a card -`PUT /boards/{boardId}/stacks/{stackId}/cards/{cardId}/unarchive` +#### Delete a board +`DELETE /boards/{boardId}` ##### Request parameters -| Parameter | Type | Description | -| --------- | ------- | --------------------------------------- | -| boardId | Integer | The id of the board the card belongs to | -| stackId | Integer | The id of the stack the card belongs to | -| cardId | Integer | The id of the card | +| Parameter | Type | Description | +| --------- | ------- | ---------------------------- | +| boardId | Integer | The id of the board to fetch | ##### Response ###### 200 Success -#### Delete a board -`DELETE /boards/{boardId}` +#### Restore a deleted board +`POST /boards/{boardId}/undo_delete` ##### Request parameters @@ -397,22 +386,40 @@ A 403 response might be returned if the user's ability to create new boards has ###### 200 Success -#### Restore a deleted board -`POST /boards/{boardId}/undo_delete` +#### Clone a board +`POST /boards/{boardId}/clone` -##### Request parameters +Creates a copy of the board. | Parameter | Type | Description | | --------- | ------- | ---------------------------- | -| boardId | Integer | The id of the board to fetch | +| boardId | Integer | The id of the board | + +##### Request body + +| Parameter | Type | Description | +| --------- | ------ | ---------------------------------------------------- | +| withCards | Bool | Setting if the cards should be copied (Default: false) | +| withAssignments | Bool | Setting if the card assignments should be cloned (Default: false) | +| withLabels | Bool | Setting if the card labels should be cloned (Default: false) | +| withDueDate | Bool | Setting if the card due dates should be cloned (Default: false) | +| moveCardsToLeftStack | Bool | Setting if all cards should be moved to the most left column (useful for To-Do / Doing / Done boards) (Default: false) | +| restoreArchivedCards | Bool | Setting if the archived cards should be unarchived (Default: false) | ##### Response ###### 200 Success + #### Add new acl rule `POST /boards/{boardId}/acl` +##### Request parameters + +| Parameter | Type | Description | +| --------- | ------- | ---------------------------- | +| boardId | Integer | The id of the board | + ##### Request body | Parameter | Type | Description | @@ -454,31 +461,18 @@ A 403 response might be returned if the user's ability to create new boards has ##### Request parameters -| Parameter | Type | Description | -| --------- | ------ | ---------------------------------------------------- | -| permissionEdit | Bool | Setting if the participant has edit permissions | -| permissionShare | Bool | Setting if the participant has sharing permissions | -| permissionManage | Bool | Setting if the participant has management permissions | - -##### Response - -###### 200 Success - -#### Clone a board -`POST /boards/{boardId}/clone` - -Creates a copy of the board. +| Parameter | Type | Description | +| --------- | ------- | ---------------------------- | +| boardId | Integer | The id of the board | +| aclId | Integer | The id of the acl | ##### Request body | Parameter | Type | Description | | --------- | ------ | ---------------------------------------------------- | -| withCards | Bool | Setting if the cards should be copied (Default: false) | -| withAssignments | Bool | Setting if the card assignments should be cloned (Default: false) | -| withLabels | Bool | Setting if the card labels should be cloned (Default: false) | -| withDueDate | Bool | Setting if the card due dates should be cloned (Default: false) | -| moveCardsToLeftStack | Bool | Setting if all cards should be moved to the most left column (useful for To-Do / Doing / Done boards) (Default: false) | -| restoreArchivedCards | Bool | Setting if the archived cards should be unarchived (Default: false) | +| permissionEdit | Bool | Setting if the participant has edit permissions | +| permissionShare | Bool | Setting if the participant has sharing permissions | +| permissionManage | Bool | Setting if the participant has management permissions | ##### Response @@ -487,6 +481,13 @@ Creates a copy of the board. #### Delete an acl rule `DELETE /boards/{boardId}/acl/{aclId}` +##### Request parameters + +| Parameter | Type | Description | +| --------- | ------- | ---------------------------- | +| boardId | Integer | The id of the board | +| aclId | Integer | The id of the acl | + ##### Response ###### 200 Success @@ -569,6 +570,12 @@ The board list endpoint supports setting an `If-Modified-Since` header to limit #### Create a new stack `POST /boards/{boardId}/stacks` +##### Request parameters + +| Parameter | Type | Description | +| --------- | ------- | ---------------------------- | +| boardId | Integer | The id of the board to fetch | + ##### Request body | Parameter | Type | Description | @@ -576,12 +583,6 @@ The board list endpoint supports setting an `If-Modified-Since` header to limit | title | String | The title of the new stack, maximum length is limited to 100 characters | | order | Integer | Order for sorting the stacks | -##### Request parameters - -| Parameter | Type | Description | -| --------- | ------- | ---------------------------- | -| boardId | Integer | The id of the board to fetch | - ##### Response ###### 200 Success @@ -697,7 +698,7 @@ The board list endpoint supports setting an `If-Modified-Since` header to limit | stackId | Integer | The id of the stack the card belongs to | | cardId | Integer | The id of the card | -##### Request data +##### Request body | Parameter | Type | Description | |-------------|-----------------|-----------------------------------------------------------------------------------------------------| @@ -754,7 +755,7 @@ The board list endpoint supports setting an `If-Modified-Since` header to limit | stackId | Integer | The id of the stack the card belongs to | | cardId | Integer | The id of the card | -##### Request data +##### Request body | Parameter | Type | Description | | --------- | ------- | --------------------------------------- | @@ -774,7 +775,7 @@ The board list endpoint supports setting an `If-Modified-Since` header to limit | stackId | Integer | The id of the stack the card belongs to | | cardId | Integer | The id of the card | -##### Request data +##### Request body | Parameter | Type | Description | | --------- | ------- | --------------------------------------- | @@ -795,7 +796,7 @@ The board list endpoint supports setting an `If-Modified-Since` header to limit | stackId | Integer | The id of the stack the card belongs to | | cardId | Integer | The id of the card | -##### Request data +##### Request body | Parameter | Type | Description | | --------- | ------- | --------------------------------------- | @@ -844,7 +845,7 @@ The request can fail with a bad request response for the following reasons: | stackId | Integer | The id of the stack the card belongs to | | cardId | Integer | The id of the card | -##### Request data +##### Request body | Parameter | Type | Description | | --------- | ------- | --------------------------------------- | @@ -865,18 +866,48 @@ The request can fail with a bad request response for the following reasons: | stackId | Integer | The id of the stack the card belongs to | | cardId | Integer | The id of the card | -##### Request data +##### Request body | Parameter | Type | Description | | --------- | ------- | ----------------------------------------------------------- | | order | Integer | The position in the stack where the card should be moved to | | stackId | Integer | The id of the stack where the card should be moved to | +##### Response + +###### 200 Success + +#### Archive a card +`PUT /boards/{boardId}/stacks/{stackId}/cards/{cardId}/archive` + +##### Request parameters + +| Parameter | Type | Description | +| --------- | ------- | --------------------------------------- | +| boardId | Integer | The id of the board the card belongs to | +| stackId | Integer | The id of the stack the card belongs to | +| cardId | Integer | The id of the card | + +##### Response + +###### 200 Success + +#### Unarchive a card +`PUT /boards/{boardId}/stacks/{stackId}/cards/{cardId}/unarchive` + +##### Request parameters + +| Parameter | Type | Description | +| --------- | ------- | --------------------------------------- | +| boardId | Integer | The id of the board the card belongs to | +| stackId | Integer | The id of the stack the card belongs to | +| cardId | Integer | The id of the card | ##### Response ###### 200 Success + ### Labels #### Get label details @@ -912,7 +943,7 @@ The request can fail with a bad request response for the following reasons: | --------- | ------- | ---------------------------------------- | | boardId | Integer | The id of the board the label belongs to | -##### Request data +##### Request body ```json { @@ -936,7 +967,7 @@ The request can fail with a bad request response for the following reasons: | labelId | Integer | The id of the label | -##### Request data +##### Request body ```json { @@ -1033,7 +1064,7 @@ The request can fail with a bad request response for the following reasons: | stackId | Integer | The id of the stack the attachment belongs to | | cardId | Integer | The id of the card the attachment belongs to | -##### Request data +##### Request body | Parameter | Type | Description | | --------- | ------- | --------------------------------------------- | @@ -1059,7 +1090,7 @@ The request can fail with a bad request response for the following reasons: | cardId | Integer | The id of the card the attachment belongs to | | attachmentId | Integer | The id of the attachment | -##### Request data +##### Request body | Parameter | Type | Description | | --------- | ------- | --------------------------------------------- | @@ -1105,35 +1136,35 @@ For now only `deck_file` is supported as an attachment type. ###### 200 Success -#### Import a board -`GET /boards/import/getSystems` +### Import API -##### Request parameters - -| Parameter | Type | Description | -| ------------ | ------- | --------------------------------------------- | -| system | Integer | The system name. Example: trello | +#### Get Systems +`GET /boards/import/getSystems` ##### Response -Make a request to see the json schema of system - ```json -{ -} +[ + "trello" +] ``` -#### Import a board -`GET /boards/import/config/system/{schema}` +#### Get System Schema +`GET /boards/import/config/system/{system}` ##### Request parameters +| Parameter | Type | Description | +| ------------ | ------- | --------------------------------------------- | +| system | Integer | The system name. Example: trello | + + ##### Response +Make a request to see the json schema of system + ```json -[ - "trello" -] +{} ``` #### Import a board @@ -1542,7 +1573,7 @@ curl -X PUT 'https://admin:admin@nextcloud/ocs/v2.php/apps/deck/api/v1.0/session ``` -#### notifies the server, that the session is still open +#### notifies the server that the session is still open `POST /session/sync` ##### Request body From a15d3478ff1af94a18a6c37f58e57f234af29951 Mon Sep 17 00:00:00 2001 From: Viktor Diezel Date: Wed, 6 Aug 2025 22:07:37 +0200 Subject: [PATCH 06/30] docs: add missing language tags to code blocks in API.md Signed-off-by: Viktor Diezel --- docs/API.md | 28 ++++++++++++++-------------- 1 file changed, 14 insertions(+), 14 deletions(-) diff --git a/docs/API.md b/docs/API.md index 8a88e9bde9..c552f83ca0 100644 --- a/docs/API.md +++ b/docs/API.md @@ -712,7 +712,7 @@ The board list endpoint supports setting an `If-Modified-Since` header to limit | done | timestamp\|null | The ISO-8601 formatted date when the card is marked as done (optional, null indicates undone state) | -``` +```json { "title": "Test card", "description": "A card description", @@ -1203,7 +1203,7 @@ Deck stores user and app configuration values globally and per board. The GET en | cardIdBadge | Determines if the ID badges are displayed on cards (boolean) | | groupLimit | Determines if creating new boards is limited to certain groups of the instance. The resulting output is an array of group objects with the id and the displayname (Admin only)| -``` +```json { "ocs": { "meta": { @@ -1250,7 +1250,7 @@ Deck stores user and app configuration values globally and per board. The GET en ##### Example request -``` +```json curl -X POST 'https://admin:admin@nextcloud.local/ocs/v2.php/apps/deck/api/v1.0/config/calendar' -H 'Accept: application/json' -H "Content-Type: application/json" -H 'OCS-APIRequest: true' --data-raw '{"value":false}' { @@ -1279,7 +1279,7 @@ curl -X POST 'https://admin:admin@nextcloud.local/ocs/v2.php/apps/deck/api/v1.0/ | limit | Integer | The maximum number of comments that should be returned, defaults to 20 | | offset | Integer | The start offset used for pagination, defaults to 0 | -``` +```bash curl 'https://admin:admin@nextcloud/ocs/v2.php/apps/deck/api/v1.0/cards/12/comments' \ -H 'Accept: application/json' -H 'OCS-APIRequest: true' ``` @@ -1290,7 +1290,7 @@ A list of comments will be provided under the `ocs.data` key. If no or no more c ###### 200 Success -``` +```json { "ocs": { "meta": { @@ -1373,7 +1373,7 @@ In case a comment is marked as a reply to another comment object, the parent com Mentions will be parsed by the server. The server will return a list of mentions in the response to this request as shown below. -``` +```bash curl -X POST 'https://admin:admin@nextcloud/ocs/v2.php/apps/deck/api/v1.0/cards/12/comments' \ -H 'Accept: application/json' -H 'OCS-APIRequest: true' -H 'Content-Type: application/json;charset=utf-8' @@ -1386,7 +1386,7 @@ A list of comments will be provided under the `ocs.data` key. If no or no more c ###### 200 Success -``` +```bash { "ocs": { "meta": { @@ -1441,7 +1441,7 @@ Mentions will be parsed by the server. The server will return a list of mentions Updating comments is limited to the current user being the same as the comment author specified in the `actorId` of the comment. -``` +```bash curl -X PUT 'https://admin:admin@nextcloud/ocs/v2.php/apps/deck/api/v1.0/cards/12/comments/123' \ -H 'Accept: application/json' -H 'OCS-APIRequest: true' -H 'Content-Type: application/json;charset=utf-8' @@ -1454,7 +1454,7 @@ A list of comments will be provided under the `ocs.data` key. If no or no more c ###### 200 Success -``` +```json { "ocs": { "meta": { @@ -1499,7 +1499,7 @@ A not found response might be returned if: Deleting comments is limited to the current user being the same as the comment author specified in the `actorId` of the comment. -``` +```bash curl -X DELETE 'https://admin:admin@nextcloud/ocs/v2.php/apps/deck/api/v1.0/cards/12/comments/123' \ -H 'Accept: application/json' -H 'OCS-APIRequest: true' -H 'Content-Type: application/json;charset=utf-8' @@ -1511,7 +1511,7 @@ A list of comments will be provided under the `ocs.data` key. If no or no more c ###### 200 Success -``` +```json { "ocs": { "meta": { @@ -1546,7 +1546,7 @@ A not found response might be returned if: | --------- | ------- | ---------------------------------------------------- | | boardId | Integer | The id of the opened board | -``` +```bash curl -X PUT 'https://admin:admin@nextcloud/ocs/v2.php/apps/deck/api/v1.0/session/create' \ -H 'Accept: application/json' -H 'OCS-APIRequest: true' \ -H 'Content-Type: application/json;charset=utf-8' \ @@ -1584,7 +1584,7 @@ curl -X PUT 'https://admin:admin@nextcloud/ocs/v2.php/apps/deck/api/v1.0/session | token | String | The session token from the /sessions/create response | -``` +```bash curl -X POST 'https://admin:admin@nextcloud/ocs/v2.php/apps/deck/api/v1.0/session/create' \ -H 'Accept: application/json' -H 'OCS-APIRequest: true' \ -H 'Content-Type: application/json;charset=utf-8' \ @@ -1621,7 +1621,7 @@ the provided token is invalid or expired | boardId | Integer | The id of the opened board | | token | String | The session token from the /sessions/create response | -``` +```bash curl -X POST 'https://admin:admin@nextcloud/ocs/v2.php/apps/deck/api/v1.0/session/close' \ -H 'Accept: application/json' -H 'OCS-APIRequest: true' \ -H 'Content-Type: application/json;charset=utf-8' \ From 70f8ebafce46c83425c451a375d3ae2c1714dd74 Mon Sep 17 00:00:00 2001 From: Viktor Diezel Date: Wed, 6 Aug 2025 22:11:13 +0200 Subject: [PATCH 07/30] docs: (opinionated) replace 'Naming' with 'Glossary' and change label description Signed-off-by: Viktor Diezel --- docs/API.md | 13 +++++-------- 1 file changed, 5 insertions(+), 8 deletions(-) diff --git a/docs/API.md b/docs/API.md index c552f83ca0..be84467e33 100644 --- a/docs/API.md +++ b/docs/API.md @@ -13,15 +13,12 @@ The REST API provides access for authenticated users to their data inside the De - The API is located at https://nextcloud.local/index.php/apps/deck/api/v1.0 - All request parameters are required, unless otherwise specified -### Naming +### Glossary -- Board is the project like grouping of tasks that can be shared to different users and groups - -- Stack is the grouping of cards which is rendered in vertical columns in the UI - -- Card is the representation of a single task - -- Labels are defined on a board level and can be assigned to any number of cards +- **Board** is the project like grouping of tasks that can be shared to different users and groups +- **Stack** is the grouping of cards which is rendered in vertical columns in the UI +- **Card** is the representation of a single task +- **Label** is a board-level tag used to categorize and prioritize cards ### Global responses From 6df9ca78c09273b555580147a67ef1a7154785ef Mon Sep 17 00:00:00 2001 From: Viktor Diezel Date: Wed, 6 Aug 2025 22:24:15 +0200 Subject: [PATCH 08/30] docs: Formatting and small text changes to the Prerequisites section Signed-off-by: Viktor Diezel --- docs/API.md | 49 +++++++++++++++++++++++++++++++++++++------------ 1 file changed, 37 insertions(+), 12 deletions(-) diff --git a/docs/API.md b/docs/API.md index be84467e33..c0e9981703 100644 --- a/docs/API.md +++ b/docs/API.md @@ -10,7 +10,7 @@ The REST API provides access for authenticated users to their data inside the De ## Prerequisites - All requests require a `OCS-APIRequest` HTTP header to be set to `true` and a `Content-Type` of `application/json`. -- The API is located at https://nextcloud.local/index.php/apps/deck/api/v1.0 +- The API is located at `/index.php/apps/deck/api/v1.0` - All request parameters are required, unless otherwise specified ### Glossary @@ -20,11 +20,13 @@ The REST API provides access for authenticated users to their data inside the De - **Card** is the representation of a single task - **Label** is a board-level tag used to categorize and prioritize cards -### Global responses +### HTTP responses + +The REST API follows conventional HTTP status codes. Successful responses have a status code of `2xx`. Client side errors are indicated as `4xx`. The most common ones are: #### 400 Bad request -In case the request is invalid, e.g. because a parameter is missing or an invalid value has been transmitted, a 400 error will be returned: +The request is invalid, e.g. because a parameter is missing or an invalid value has been transmitted. ```json { @@ -35,7 +37,7 @@ In case the request is invalid, e.g. because a parameter is missing or an invali #### 403 Permission denied -In any case a user doesn't have access to a requested entity, a 403 error will be returned: +The user doesn't have access to a requested entity. ```json { @@ -44,11 +46,34 @@ In any case a user doesn't have access to a requested entity, a 403 error will b } ``` +#### 404 Not found + +The requested entity was not found. + +```json +{ + "status": 404, + "message": "Card not found" +} +``` + +#### 405 Method not allowed + +The used combination of URL and HTTP method is not allowed. Most likely you have used a wrong HTTP method or URL. + +```json +{ + "status": 405, + "message": "Method not allowed" +} +``` + ### Formats #### Date -Datetime values in request data need to be provided in ISO-8601. Example: 2020-01-20T09:52:43+00:00 +Datetime values in request data need to be provided in ISO-8601.
+Example: `2020-01-20T09:52:43+00:00` ### Headers @@ -57,9 +82,9 @@ Datetime values in request data need to be provided in ISO-8601. Example: 2020-0 Some index endpoints support limiting the result set to entries that have been changed since the given time. The supported date formats are: -* IMF-fixdate: `Sun, 03 Aug 2019 10:34:12 GMT` -* (obsolete) RFC 850: `Sunday, 03-Aug-19 10:34:12 GMT` -* (obsolete) ANSI C asctime(): `Sun Aug 3 10:34:12 2019` +- IMF-fixdate: `Sun, 03 Aug 2019 10:34:12 GMT` +- _(obsolete)_ RFC 850: `Sunday, 03-Aug-19 10:34:12 GMT` +- _(obsolete)_ ANSI C asctime(): `Sun Aug 3 10:34:12 2019` It is highly recommended to only use the IMF-fixdate format. Note that according to [RFC2616](https://tools.ietf.org/html/rfc2616#section-3.3) all HTTP date/time stamps MUST be represented in Greenwich Mean Time (GMT), without exception. @@ -117,9 +142,9 @@ This API version has become available with **Deck 1.3.0**. ### API version 1.2 (unreleased) - Endpoints for the new import functionality have been added: - - [GET /boards/import/getSystems - Import a board](#get-boardsimportgetsystems-import-a-board) - - [GET /boards/import/config/system/{schema} - Import a board](#get-boardsimportconfigsystemschema-import-a-board) - - [POST /boards/import - Import a board](#post-boardsimport-import-a-board) + - [GET /boards/import/getSystems - Get Systems](#get-systems) + - [GET /boards/import/config/system/{schema} - Get System Schema](#get-system-schema) + - [POST /boards/import - Import board](#import-board) - The `done` property was added to cards ## Endpoints @@ -1164,7 +1189,7 @@ Make a request to see the json schema of system {} ``` -#### Import a board +#### Import board `POST /boards/import` ##### Request parameters From e8c9907bd5a95f29db1ea003d11d68378638bddc Mon Sep 17 00:00:00 2001 From: Viktor Diezel Date: Wed, 6 Aug 2025 22:27:00 +0200 Subject: [PATCH 09/30] docs: add permalinks Signed-off-by: Viktor Diezel --- docs/extra.css | 6 +++++- mkdocs.yml | 3 +++ 2 files changed, 8 insertions(+), 1 deletion(-) diff --git a/docs/extra.css b/docs/extra.css index be6cc3def2..325678bc6b 100644 --- a/docs/extra.css +++ b/docs/extra.css @@ -13,4 +13,8 @@ .wy-menu-vertical li.toctree-l2 li.toctree-l3.current li.toctree-l4>a { padding-inline-start: 3.5em; -} \ No newline at end of file +} + +.headerlink { + font-size: 1.125rem !important; +} diff --git a/mkdocs.yml b/mkdocs.yml index bab07d06ce..dcb695bef1 100644 --- a/mkdocs.yml +++ b/mkdocs.yml @@ -16,3 +16,6 @@ nav: - Import documentation: - Implement import: implement-import.md - Class diagram: import-class-diagram.md +markdown_extensions: + - toc: + permalink: "#" From 2b4fd90fdda9c7d9ef258104315fa4fe12c34d92 Mon Sep 17 00:00:00 2001 From: Viktor Diezel Date: Wed, 6 Aug 2025 22:39:55 +0200 Subject: [PATCH 10/30] docs: add missing documenation for v1.1 atttachment endpoints Signed-off-by: Viktor Diezel --- docs/API.md | 25 ++++++++++++++++++++++++- 1 file changed, 24 insertions(+), 1 deletion(-) diff --git a/docs/API.md b/docs/API.md index c0e9981703..d10fc9ecb0 100644 --- a/docs/API.md +++ b/docs/API.md @@ -72,7 +72,7 @@ The used combination of URL and HTTP method is not allowed. Most likely you have #### Date -Datetime values in request data need to be provided in ISO-8601.
+Datetime values in request data need to be provided in ISO-8601. Example: `2020-01-20T09:52:43+00:00` ### Headers @@ -1060,8 +1060,13 @@ The request can fail with a bad request response for the following reasons: ``` #### Get the attachment file + +v1.0 `GET /boards/{boardId}/stacks/{stackId}/cards/{cardId}/attachments/{attachmentId}` +v1.1 +`GET /boards/{boardId}/stacks/{stackId}/cards/{cardId}/attachments/{type}/{attachmentId}` + ##### Request parameters | Parameter | Type | Description | @@ -1070,6 +1075,7 @@ The request can fail with a bad request response for the following reasons: | stackId | Integer | The id of the stack the attachment belongs to | | cardId | Integer | The id of the card the attachment belongs to | | attachmentId | Integer | The id of the attachment | +| type | String | `file` \| `deck_app` | ##### Response @@ -1101,8 +1107,13 @@ The request can fail with a bad request response for the following reasons: ###### 200 Success #### Update an attachment + +v1.0 `PUT /boards/{boardId}/stacks/{stackId}/cards/{cardId}/attachments/{attachmentId}` +v1.1 +`PUT /boards/{boardId}/stacks/{stackId}/cards/{cardId}/attachments/{type}/{attachmentId}` + ##### Request parameters | Parameter | Type | Description | @@ -1111,6 +1122,7 @@ The request can fail with a bad request response for the following reasons: | stackId | Integer | The id of the stack the attachment belongs to | | cardId | Integer | The id of the card the attachment belongs to | | attachmentId | Integer | The id of the attachment | +| type | String | `file` \| `deck_app` | ##### Request body @@ -1126,8 +1138,12 @@ For now only `deck_file` is supported as an attachment type. ###### 200 Success #### Delete an attachment + +v1.0 `DELETE /boards/{boardId}/stacks/{stackId}/cards/{cardId}/attachments/{attachmentId}` +v1.1 +`DELETE /boards/{boardId}/stacks/{stackId}/cards/{cardId}/attachments/{type}/{attachmentId}` ##### Request parameters @@ -1137,14 +1153,20 @@ For now only `deck_file` is supported as an attachment type. | stackId | Integer | The id of the stack the attachment belongs to | | cardId | Integer | The id of the card the attachment belongs to | | attachmentId | Integer | The id of the attachment | +| type | String | `file` \| `deck_app` | ##### Response ###### 200 Success #### Restore a deleted attachment + +v1.0 `PUT /boards/{boardId}/stacks/{stackId}/cards/{cardId}/attachments/{attachmentId}/restore` +v1.1 +`PUT /boards/{boardId}/stacks/{stackId}/cards/{cardId}/attachments/{type}/{attachmentId}/restore` + ##### Request parameters | Parameter | Type | Description | @@ -1153,6 +1175,7 @@ For now only `deck_file` is supported as an attachment type. | stackId | Integer | The id of the stack the attachment belongs to | | cardId | Integer | The id of the card the attachment belongs to | | attachmentId | Integer | The id of the attachment | +| type | String | `file` \| `deck_app` | ##### Response From 529a4dd635cccdf110f7c29a0224147b850081b6 Mon Sep 17 00:00:00 2001 From: Viktor Diezel Date: Wed, 6 Aug 2025 23:13:30 +0200 Subject: [PATCH 11/30] docs: Separate endpoint name and description for better navigation entries Signed-off-by: Viktor Diezel --- docs/API.md | 236 ++++++++++++++++++++++++++++++++++++++++------------ 1 file changed, 185 insertions(+), 51 deletions(-) diff --git a/docs/API.md b/docs/API.md index d10fc9ecb0..7e8c6e76c1 100644 --- a/docs/API.md +++ b/docs/API.md @@ -151,7 +151,10 @@ This API version has become available with **Deck 1.3.0**. ### Boards -#### Get a list of boards +#### List boards + +Get a list of all user boards. + `GET /boards` ##### Headers @@ -162,7 +165,7 @@ The board list endpoint supports setting an `If-Modified-Since` header to limit | Parameter | Type | Description | | --------- | ------- | ---------------------------- | -| details | Bool | **Optional** Enhance boards with details about labels, stacks and users | +| details | Bool | _(optional)_ enhance boards with details about labels, stacks and users | ##### Response @@ -202,7 +205,10 @@ Returns an array of board items ] ``` -#### Create a new board +#### Create board + +Create a new board. The user's ability to create new boards can be disabled by the administrator. For checking this before, see the `canCreateBoards` value in the [Nextcloud capabilties](./API-Nextcloud.md). + `POST /boards` ##### Request body @@ -277,11 +283,10 @@ Returns an array of board items } ``` -###### 403 Forbidden +#### Get board -A 403 response might be returned if the user's ability to create new boards has been disabled by the administrator. For checking this before, see the `canCreateBoards` value in the [Nextcloud capabilties](./API-Nextcloud.md). +Get a board by ID. -#### Get board details `GET /boards/{boardId}` ##### Request parameters @@ -353,7 +358,10 @@ A 403 response might be returned if the user's ability to create new boards has } ``` -#### Update board details +#### Update board + +Update a board by ID. + `PUT /boards/{boardId}` ##### Request parameters @@ -382,7 +390,10 @@ A 403 response might be returned if the user's ability to create new boards has ###### 200 Success -#### Delete a board +#### Delete board + +Delete a board by ID. + `DELETE /boards/{boardId}` ##### Request parameters @@ -395,7 +406,10 @@ A 403 response might be returned if the user's ability to create new boards has ###### 200 Success -#### Restore a deleted board +#### Restore board + +Restore a deleted board by ID. + `POST /boards/{boardId}/undo_delete` ##### Request parameters @@ -408,7 +422,10 @@ A 403 response might be returned if the user's ability to create new boards has ###### 200 Success -#### Clone a board +#### Clone board + +Clone a board by ID. + `POST /boards/{boardId}/clone` Creates a copy of the board. @@ -432,8 +449,10 @@ Creates a copy of the board. ###### 200 Success +#### Create ACL rule + +Create an ACL for a board. -#### Add new acl rule `POST /boards/{boardId}/acl` ##### Request parameters @@ -478,7 +497,10 @@ Creates a copy of the board. }] ``` -#### Update an acl rule +#### Update ACL rule + +Update an ACL by ID. + `PUT /boards/{boardId}/acl/{aclId}` ##### Request parameters @@ -500,7 +522,10 @@ Creates a copy of the board. ###### 200 Success -#### Delete an acl rule +#### Delete ACL rule + +Delete an ACL by ID. + `DELETE /boards/{boardId}/acl/{aclId}` ##### Request parameters @@ -516,7 +541,10 @@ Creates a copy of the board. ### Stacks -#### Get stacks +#### List stacks + +Get a list of all board stacks. + `GET /boards/{boardId}/stacks` ##### Headers @@ -548,7 +576,10 @@ The board list endpoint supports setting an `If-Modified-Since` header to limit ###### 200 Success -#### Get list of archived stacks +#### List archived stacks + +Get a list of archived stacks + `GET /boards/{boardId}/stacks/archived` ##### Request parameters @@ -575,7 +606,10 @@ The board list endpoint supports setting an `If-Modified-Since` header to limit ###### 200 Success -#### Get stack details +#### Get stack + +Get a stack by ID. + `GET /boards/{boardId}/stacks/{stackId}` ##### Request parameters @@ -589,7 +623,10 @@ The board list endpoint supports setting an `If-Modified-Since` header to limit ###### 200 Success -#### Create a new stack +#### Create stack + +Create a stack on the board. + `POST /boards/{boardId}/stacks` ##### Request parameters @@ -609,7 +646,10 @@ The board list endpoint supports setting an `If-Modified-Since` header to limit ###### 200 Success -#### Update stack details +#### Update stack + +Update a stack by ID. + `PUT /boards/{boardId}/stacks/{stackId}` ##### Request parameters @@ -630,7 +670,10 @@ The board list endpoint supports setting an `If-Modified-Since` header to limit ###### 200 Success -#### Delete a stack +#### Delete stack + +Delete a stack by ID. + `DELETE /boards/{boardId}/stacks/{stackId}` ##### Request parameters @@ -646,7 +689,10 @@ The board list endpoint supports setting an `If-Modified-Since` header to limit ### Cards -#### Get card details +#### Get card + +Get a card by ID. + `GET /boards/{boardId}/stacks/{stackId}/cards/{cardId}` ##### Request parameters @@ -661,7 +707,10 @@ The board list endpoint supports setting an `If-Modified-Since` header to limit ###### 200 Success -#### Create a new card +#### Create card + +Crreate a card on the board stack. + `POST /boards/{boardId}/stacks/{stackId}/cards` ##### Request parameters @@ -709,7 +758,10 @@ The board list endpoint supports setting an `If-Modified-Since` header to limit ###### 200 Success -#### Update card details +#### Update card + +Update a card by ID. + `PUT /boards/{boardId}/stacks/{stackId}/cards/{cardId}` ##### Request parameters @@ -751,7 +803,10 @@ The board list endpoint supports setting an `If-Modified-Since` header to limit ###### 200 Success -#### Delete a card +#### Delete card + +Delete a card by ID. + `DELETE /boards/{boardId}/stacks/{stackId}/cards/{cardId}` ##### Request parameters @@ -766,7 +821,10 @@ The board list endpoint supports setting an `If-Modified-Since` header to limit ###### 200 Success -#### Assign a label to a card +#### Assign label + +Assign a board label to a card. + `PUT /boards/{boardId}/stacks/{stackId}/cards/{cardId}/assignLabel` ##### Request parameters @@ -786,7 +844,10 @@ The board list endpoint supports setting an `If-Modified-Since` header to limit ###### 200 Success -#### Remove a label from a card +#### Unassign label + +Unassign a board label from a card. + `PUT /boards/{boardId}/stacks/{stackId}/cards/{cardId}/removeLabel` ##### Request parameters @@ -807,7 +868,10 @@ The board list endpoint supports setting an `If-Modified-Since` header to limit ###### 200 Success -#### Assign a user to a card +#### Assign user + +Assign a board user to a card. + `PUT /boards/{boardId}/stacks/{stackId}/cards/{cardId}/assignUser` ##### Request parameters @@ -855,8 +919,10 @@ The request can fail with a bad request response for the following reasons: - The user is already assigned to the card - The user is not part of the board +#### Unassign user + +Unassing a user from a card. -#### Unassign a user from a card `PUT /boards/{boardId}/stacks/{stackId}/cards/{cardId}/unassignUser` ##### Request parameters @@ -877,7 +943,10 @@ The request can fail with a bad request response for the following reasons: ###### 200 Success -#### Change the sorting order of a card +#### Move card + +Update the order and/or the stack of the card. + `PUT /boards/{boardId}/stacks/{stackId}/cards/{cardId}/reorder` ##### Request parameters @@ -899,7 +968,10 @@ The request can fail with a bad request response for the following reasons: ###### 200 Success -#### Archive a card +#### Archive card + +Archive a card. + `PUT /boards/{boardId}/stacks/{stackId}/cards/{cardId}/archive` ##### Request parameters @@ -914,7 +986,10 @@ The request can fail with a bad request response for the following reasons: ###### 200 Success -#### Unarchive a card +#### Unarchive card + +Unarchive a card. + `PUT /boards/{boardId}/stacks/{stackId}/cards/{cardId}/unarchive` ##### Request parameters @@ -929,10 +1004,12 @@ The request can fail with a bad request response for the following reasons: ###### 200 Success - ### Labels -#### Get label details +#### Get label + +Get a label by ID. + `GET /boards/{boardId}/labels/{labelId}` ##### Request parameters @@ -956,7 +1033,10 @@ The request can fail with a bad request response for the following reasons: } ``` -#### Create a new label +#### Create label + +Create a label. + `POST /boards/{boardId}/labels` ##### Request parameters @@ -978,7 +1058,10 @@ The request can fail with a bad request response for the following reasons: ###### 200 Success -#### Update label details +#### Update label + +Update a label by ID. + `PUT /boards/{boardId}/labels/{labelId}` ##### Request parameters @@ -1002,7 +1085,10 @@ The request can fail with a bad request response for the following reasons: ###### 200 Success -#### Delete a label +#### Delete label + +Delete a label by ID. + `DELETE /boards/{boardId}/labels/{labelId}` ##### Request parameters @@ -1018,7 +1104,11 @@ The request can fail with a bad request response for the following reasons: ### Attachments -#### Get a list of attachments +#### List attachments + +Get a list of all card attachments. When api-Version `v1.0` is used, then this endpoint returns only +attachments of type `deck_file`. + `GET /boards/{boardId}/stacks/{stackId}/cards/{cardId}/attachments` ##### Request parameters @@ -1059,7 +1149,9 @@ The request can fail with a bad request response for the following reasons: ``` -#### Get the attachment file +#### Get attachment + +Get a card attachment by ID. v1.0 `GET /boards/{boardId}/stacks/{stackId}/cards/{cardId}/attachments/{attachmentId}` @@ -1081,7 +1173,10 @@ v1.1 ###### 200 Success -#### Upload an attachment +#### Upload attachment + +Upload a card attachment. + `POST /boards/{boardId}/stacks/{stackId}/cards/{cardId}/attachments` ##### Request parameters @@ -1106,7 +1201,9 @@ v1.1 ###### 200 Success -#### Update an attachment +#### Update attachment + +Update a card attachment by ID. v1.0 `PUT /boards/{boardId}/stacks/{stackId}/cards/{cardId}/attachments/{attachmentId}` @@ -1137,7 +1234,9 @@ For now only `deck_file` is supported as an attachment type. ###### 200 Success -#### Delete an attachment +#### Delete attachment + +Delete a card attachment by ID. v1.0 `DELETE /boards/{boardId}/stacks/{stackId}/cards/{cardId}/attachments/{attachmentId}` @@ -1159,7 +1258,9 @@ v1.1 ###### 200 Success -#### Restore a deleted attachment +#### Restore attachment + +Restore a deleted card attachment by ID. v1.0 `PUT /boards/{boardId}/stacks/{stackId}/cards/{cardId}/attachments/{attachmentId}/restore` @@ -1184,6 +1285,9 @@ v1.1 ### Import API #### Get Systems + +Get the allowed import systems. + `GET /boards/import/getSystems` ##### Response @@ -1195,6 +1299,9 @@ v1.1 ``` #### Get System Schema + +Get a system schema. + `GET /boards/import/config/system/{system}` ##### Request parameters @@ -1203,7 +1310,6 @@ v1.1 | ------------ | ------- | --------------------------------------------- | | system | Integer | The system name. Example: trello | - ##### Response Make a request to see the json schema of system @@ -1213,6 +1319,9 @@ Make a request to see the json schema of system ``` #### Import board + +Import a board from another system. + `POST /boards/import` ##### Request parameters @@ -1236,7 +1345,10 @@ This has the benefit that both the web UI as well as external integrations can u Deck stores user and app configuration values globally and per board. The GET endpoint allows to fetch the current global configuration while board settings will be exposed through the board element on the regular API endpoints. -#### Fetch app configuration values +#### Get app configuration + +Get the configuration of the deck app. + `GET /api/v1.0/config` ##### Response @@ -1272,9 +1384,11 @@ Deck stores user and app configuration values globally and per board. The GET en ``` -#### Set a config value -`POST /api/v1.0/config/{id}/{key}` +#### Set config value + +Set a configuration value by key. +`POST /api/v1.0/config/{id}/{key}` ##### Request parameters @@ -1314,6 +1428,9 @@ curl -X POST 'https://admin:admin@nextcloud.local/ocs/v2.php/apps/deck/api/v1.0/ ### Comments #### List comments + +List comments for a card. + `GET /cards/{cardId}/comments` ##### Request parameters @@ -1404,8 +1521,10 @@ In case a comment is marked as a reply to another comment object, the parent com ] ``` +#### Create comment + +Create comment for a card. -#### Create a new comment `POST /cards/{cardId}/comments` ##### Request parameters @@ -1470,8 +1589,10 @@ A not found response might be returned if: - The card for the given cardId could not be found - The parent comment could not be found +#### Update comment + +Update a card comment by ID. -#### Update a comment `PUT /cards/{cardId}/comments/{commentId}` ##### Request parameters @@ -1532,7 +1653,10 @@ A not found response might be returned if: - The card for the given cardId could not be found - The comment could not be found -#### Delete a comment +#### Delete comment + +Delete a card comment by ID. + `DELETE /cards/{cardId}/comments/{commentId}` ##### Request parameters @@ -1582,7 +1706,10 @@ A not found response might be returned if: ### Sessions -#### creates a new session +#### Creates session + +Create a session. + `PUT /session/create` ##### Request parameters @@ -1617,8 +1744,10 @@ curl -X PUT 'https://admin:admin@nextcloud/ocs/v2.php/apps/deck/api/v1.0/session } ``` +#### Sync session + +Notify the server that the session is still open: -#### notifies the server that the session is still open `POST /session/sync` ##### Request body @@ -1639,6 +1768,7 @@ curl -X POST 'https://admin:admin@nextcloud/ocs/v2.php/apps/deck/api/v1.0/sessio ##### Response ###### 200 Success + ```json { "ocs": { @@ -1653,10 +1783,13 @@ curl -X POST 'https://admin:admin@nextcloud/ocs/v2.php/apps/deck/api/v1.0/sessio ``` ###### 404 Not Found + the provided token is invalid or expired +#### Close session + +Close a session. -#### closes the session `POST /session/close` ##### Request body @@ -1676,6 +1809,7 @@ curl -X POST 'https://admin:admin@nextcloud/ocs/v2.php/apps/deck/api/v1.0/sessio ##### Response ###### 200 Success + ```json { "ocs": { From b10a46e38752bebac57353e4c10d60e7d5c12882 Mon Sep 17 00:00:00 2001 From: Viktor Diezel Date: Wed, 6 Aug 2025 23:43:01 +0200 Subject: [PATCH 12/30] docs: (opinionated) removes 200 success heading from responses and adds a short description on the return value Signed-off-by: Viktor Diezel --- docs/API.md | 155 ++++++++++++++++++++++++---------------------------- 1 file changed, 70 insertions(+), 85 deletions(-) diff --git a/docs/API.md b/docs/API.md index 7e8c6e76c1..206bcf2046 100644 --- a/docs/API.md +++ b/docs/API.md @@ -169,10 +169,6 @@ The board list endpoint supports setting an `If-Modified-Since` header to limit ##### Response -###### 200 Success - -Returns an array of board items - ```json [ { @@ -227,8 +223,6 @@ Create a new board. The user's ability to create new boards can be disabled by t ##### Response -###### 200 Success - ```json { "title": "Board title", @@ -297,8 +291,6 @@ Get a board by ID. ##### Response -###### 200 Success - ```json { "title": "Board title", @@ -388,7 +380,7 @@ Update a board by ID. ##### Response -###### 200 Success +Returns the updated board. #### Delete board @@ -404,7 +396,7 @@ Delete a board by ID. ##### Response -###### 200 Success +Returns the deleted board. The `deletedAt`-key contains the UNIX timestamp at deletion. #### Restore board @@ -420,7 +412,7 @@ Restore a deleted board by ID. ##### Response -###### 200 Success +Returns the restored board. #### Clone board @@ -447,7 +439,7 @@ Creates a copy of the board. ##### Response -###### 200 Success +Returns the restored board. #### Create ACL rule @@ -478,8 +470,6 @@ Create an ACL for a board. ##### Response -###### 200 Success - ```json [{ "participant": { @@ -518,9 +508,9 @@ Update an ACL by ID. | permissionShare | Bool | Setting if the participant has sharing permissions | | permissionManage | Bool | Setting if the participant has management permissions | -##### Response +#### Response -###### 200 Success +Returns the updated ACL. #### Delete ACL rule @@ -537,7 +527,7 @@ Delete an ACL by ID. ##### Response -###### 200 Success +Returns the deleted ACL. ### Stacks @@ -551,7 +541,6 @@ Get a list of all board stacks. The board list endpoint supports setting an `If-Modified-Since` header to limit the results to entities that are changed after the provided time. - ##### Request parameters | Parameter | Type | Description | @@ -574,8 +563,6 @@ The board list endpoint supports setting an `If-Modified-Since` header to limit ] ``` -###### 200 Success - #### List archived stacks Get a list of archived stacks @@ -604,8 +591,6 @@ Get a list of archived stacks ] ``` -###### 200 Success - #### Get stack Get a stack by ID. @@ -621,7 +606,17 @@ Get a stack by ID. ##### Response -###### 200 Success +```json +{ + "title": "ToDo", + "boardId": 2, + "deletedAt": 0, + "lastModified": 1541426139, + "cards": [...], + "order": 999, + "id": 4 +} +``` #### Create stack @@ -644,7 +639,7 @@ Create a stack on the board. ##### Response -###### 200 Success +Returns the created stack. #### Update stack @@ -668,7 +663,7 @@ Update a stack by ID. ##### Response -###### 200 Success +Returns the updated stack. #### Delete stack @@ -685,7 +680,7 @@ Delete a stack by ID. ##### Response -###### 200 Success +Returns the deleted stack. The `deletedAt`-key contains the UNIX timestamp at deletion. ### Cards @@ -705,7 +700,29 @@ Get a card by ID. ##### Response -###### 200 Success +```json +{ + "title":"Test", + "description":null, + "stackId":6, + "type":"plain", + "lastModified":1541528026, + "createdAt":1541528026, + "labels":null, + "assignedUsers":null, + "attachments":null, + "attachmentCount":null, + "owner":"admin", + "order":999, + "archived":false, + "done":null, + "duedate": "2019-12-24T19:29:30+00:00", + "deletedAt":0, + "commentsUnread":0, + "id":10, + "overdue":0 +} +``` #### Create card @@ -756,8 +773,6 @@ Crreate a card on the board stack. } ``` -###### 200 Success - #### Update card Update a card by ID. @@ -785,7 +800,6 @@ Update a card by ID. | archived | bool | Whether the card is archived or not | | done | timestamp\|null | The ISO-8601 formatted date when the card is marked as done (optional, null indicates undone state) | - ```json { "title": "Test card", @@ -801,7 +815,7 @@ Update a card by ID. ##### Response -###### 200 Success +Returns the updated card. #### Delete card @@ -819,7 +833,7 @@ Delete a card by ID. ##### Response -###### 200 Success +Returns the deleted card. The `deletedAt`-key contains the UNIX timestamp at deletion. #### Assign label @@ -840,9 +854,10 @@ Assign a board label to a card. | Parameter | Type | Description | | --------- | ------- | --------------------------------------- | | labelId | Integer | The label id to assign to the card | + ##### Response -###### 200 Success +Returns an empty response. #### Unassign label @@ -866,7 +881,7 @@ Unassign a board label from a card. ##### Response -###### 200 Success +Returns an empty response. #### Assign user @@ -890,8 +905,6 @@ Assign a board user to a card. ##### Response -###### 200 Success - ```json { "id": 3, @@ -904,21 +917,6 @@ Assign a board user to a card. } ``` -###### 400 Bad request - -```json -{ - "status": 400, - "message": "The user is already assigned to the card" -} -``` - -The request can fail with a bad request response for the following reasons: - -- Missing or wrongly formatted request parameters -- The user is already assigned to the card -- The user is not part of the board - #### Unassign user Unassing a user from a card. @@ -941,7 +939,7 @@ Unassing a user from a card. ##### Response -###### 200 Success +Returns the removed user assignment. #### Move card @@ -966,7 +964,7 @@ Update the order and/or the stack of the card. ##### Response -###### 200 Success +Returns a list of stack cards in the updated order. #### Archive card @@ -984,7 +982,7 @@ Archive a card. ##### Response -###### 200 Success +Returns the archived card. #### Unarchive card @@ -1002,7 +1000,7 @@ Unarchive a card. ##### Response -###### 200 Success +Returns the unarchived card. ### Labels @@ -1021,8 +1019,6 @@ Get a label by ID. ##### Response -###### 200 Success - ```json { "title": "Abgeschlossen", @@ -1056,7 +1052,15 @@ Create a label. ##### Response -###### 200 Success +```json +{ + "title": "Finished", + "color": "31CC7C", + "boardId": "2", + "cardId": null, + "id": 5 +} +``` #### Update label @@ -1071,7 +1075,6 @@ Update a label by ID. | boardId | Integer | The id of the board the label belongs to | | labelId | Integer | The id of the label | - ##### Request body ```json @@ -1083,7 +1086,7 @@ Update a label by ID. ##### Response -###### 200 Success +Returns the updated label. #### Delete label @@ -1100,7 +1103,7 @@ Delete a label by ID. ##### Response -###### 200 Success +Returns the deleted label. ### Attachments @@ -1121,8 +1124,6 @@ attachments of type `deck_file`. ##### Response -###### 200 Success - ```json [ { @@ -1171,7 +1172,7 @@ v1.1 ##### Response -###### 200 Success +Returns the card attachment. #### Upload attachment @@ -1199,7 +1200,7 @@ Upload a card attachment. ##### Response -###### 200 Success +Returns the card attachement. #### Update attachment @@ -1232,7 +1233,7 @@ For now only `deck_file` is supported as an attachment type. ##### Response -###### 200 Success +Returns the updated card attachment. #### Delete attachment @@ -1256,7 +1257,7 @@ v1.1 ##### Response -###### 200 Success +Returns the deleted attachment. #### Restore attachment @@ -1280,7 +1281,7 @@ v1.1 ##### Response -###### 200 Success +Returns the restored attachment. ### Import API @@ -1312,8 +1313,6 @@ Get a system schema. ##### Response -Make a request to see the json schema of system - ```json {} ``` @@ -1334,7 +1333,7 @@ Import a board from another system. ##### Response -###### 200 Success +Returns the imported board. ## OCS API @@ -1450,8 +1449,6 @@ curl 'https://admin:admin@nextcloud/ocs/v2.php/apps/deck/api/v1.0/cards/12/comme A list of comments will be provided under the `ocs.data` key. If no or no more comments are available the list will be empty. -###### 200 Success - ```json { "ocs": { @@ -1548,8 +1545,6 @@ curl -X POST 'https://admin:admin@nextcloud/ocs/v2.php/apps/deck/api/v1.0/cards/ A list of comments will be provided under the `ocs.data` key. If no or no more comments are available the list will be empty. -###### 200 Success - ```bash { "ocs": { @@ -1618,8 +1613,6 @@ curl -X PUT 'https://admin:admin@nextcloud/ocs/v2.php/apps/deck/api/v1.0/cards/1 A list of comments will be provided under the `ocs.data` key. If no or no more comments are available the list will be empty. -###### 200 Success - ```json { "ocs": { @@ -1678,8 +1671,6 @@ curl -X DELETE 'https://admin:admin@nextcloud/ocs/v2.php/apps/deck/api/v1.0/card A list of comments will be provided under the `ocs.data` key. If no or no more comments are available the list will be empty. -###### 200 Success - ```json { "ocs": { @@ -1727,8 +1718,6 @@ curl -X PUT 'https://admin:admin@nextcloud/ocs/v2.php/apps/deck/api/v1.0/session ##### Response -###### 200 Success - ```json { "ocs": { @@ -1767,8 +1756,6 @@ curl -X POST 'https://admin:admin@nextcloud/ocs/v2.php/apps/deck/api/v1.0/sessio ##### Response -###### 200 Success - ```json { "ocs": { @@ -1808,8 +1795,6 @@ curl -X POST 'https://admin:admin@nextcloud/ocs/v2.php/apps/deck/api/v1.0/sessio ##### Response -###### 200 Success - ```json { "ocs": { From 66cf7609b55eb8c0f5226ed3de7c495ea05cf928 Mon Sep 17 00:00:00 2001 From: Viktor Diezel Date: Wed, 6 Aug 2025 23:49:41 +0200 Subject: [PATCH 13/30] docs: (opinionated) removes the error responses from endpoints Signed-off-by: Viktor Diezel --- docs/API.md | 37 ------------------------------------- 1 file changed, 37 deletions(-) diff --git a/docs/API.md b/docs/API.md index 206bcf2046..83b497b471 100644 --- a/docs/API.md +++ b/docs/API.md @@ -1573,17 +1573,6 @@ A list of comments will be provided under the `ocs.data` key. If no or no more c } ``` -###### 400 Bad request - -A bad request response is returned if invalid input values are provided. The response message will contain details about which part was not valid. - -###### 404 Not found - -A not found response might be returned if: - -- The card for the given cardId could not be found -- The parent comment could not be found - #### Update comment Update a card comment by ID. @@ -1635,17 +1624,6 @@ A list of comments will be provided under the `ocs.data` key. If no or no more c } ``` -###### 400 Bad request - -A bad request response is returned if invalid input values are provided. The response message will contain details about which part was not valid. - -###### 404 Not found - -A not found response might be returned if: - -- The card for the given cardId could not be found -- The comment could not be found - #### Delete comment Delete a card comment by ID. @@ -1684,17 +1662,6 @@ A list of comments will be provided under the `ocs.data` key. If no or no more c } ``` -###### 400 Bad request - -A bad request response is returned if invalid input values are provided. The response message will contain details about which part was not valid. - -###### 404 Not found - -A not found response might be returned if: - -- The card for the given cardId could not be found -- The comment could not be found - ### Sessions #### Creates session @@ -1769,10 +1736,6 @@ curl -X POST 'https://admin:admin@nextcloud/ocs/v2.php/apps/deck/api/v1.0/sessio } ``` -###### 404 Not Found - -the provided token is invalid or expired - #### Close session Close a session. From f14e47ca8f352f39c1d27b72fa8cb3dbe766d128 Mon Sep 17 00:00:00 2001 From: Viktor Diezel Date: Thu, 7 Aug 2025 00:04:11 +0200 Subject: [PATCH 14/30] docs: (opinionated) better visual separation between endpoints Signed-off-by: Viktor Diezel --- docs/API.md | 100 ++++++++++++++++++++++++------------------------- docs/extra.css | 5 +++ mkdocs.yml | 1 + 3 files changed, 56 insertions(+), 50 deletions(-) diff --git a/docs/API.md b/docs/API.md index 83b497b471..a73745e7d5 100644 --- a/docs/API.md +++ b/docs/API.md @@ -151,7 +151,7 @@ This API version has become available with **Deck 1.3.0**. ### Boards -#### List boards +#### List boards {.ep-heading} Get a list of all user boards. @@ -201,7 +201,7 @@ The board list endpoint supports setting an `If-Modified-Since` header to limit ] ``` -#### Create board +#### Create board {.ep-heading} Create a new board. The user's ability to create new boards can be disabled by the administrator. For checking this before, see the `canCreateBoards` value in the [Nextcloud capabilties](./API-Nextcloud.md). @@ -277,7 +277,7 @@ Create a new board. The user's ability to create new boards can be disabled by t } ``` -#### Get board +#### Get board {.ep-heading} Get a board by ID. @@ -350,7 +350,7 @@ Get a board by ID. } ``` -#### Update board +#### Update board {.ep-heading} Update a board by ID. @@ -382,7 +382,7 @@ Update a board by ID. Returns the updated board. -#### Delete board +#### Delete board {.ep-heading} Delete a board by ID. @@ -398,7 +398,7 @@ Delete a board by ID. Returns the deleted board. The `deletedAt`-key contains the UNIX timestamp at deletion. -#### Restore board +#### Restore board {.ep-heading} Restore a deleted board by ID. @@ -414,7 +414,7 @@ Restore a deleted board by ID. Returns the restored board. -#### Clone board +#### Clone board {.ep-heading} Clone a board by ID. @@ -441,7 +441,7 @@ Creates a copy of the board. Returns the restored board. -#### Create ACL rule +#### Create ACL rule {.ep-heading} Create an ACL for a board. @@ -487,7 +487,7 @@ Create an ACL for a board. }] ``` -#### Update ACL rule +#### Update ACL rule {.ep-heading} Update an ACL by ID. @@ -508,11 +508,11 @@ Update an ACL by ID. | permissionShare | Bool | Setting if the participant has sharing permissions | | permissionManage | Bool | Setting if the participant has management permissions | -#### Response +#### Response {.ep-heading} Returns the updated ACL. -#### Delete ACL rule +#### Delete ACL rule {.ep-heading} Delete an ACL by ID. @@ -531,7 +531,7 @@ Returns the deleted ACL. ### Stacks -#### List stacks +#### List stacks {.ep-heading} Get a list of all board stacks. @@ -563,7 +563,7 @@ The board list endpoint supports setting an `If-Modified-Since` header to limit ] ``` -#### List archived stacks +#### List archived stacks {.ep-heading} Get a list of archived stacks @@ -591,7 +591,7 @@ Get a list of archived stacks ] ``` -#### Get stack +#### Get stack {.ep-heading} Get a stack by ID. @@ -618,7 +618,7 @@ Get a stack by ID. } ``` -#### Create stack +#### Create stack {.ep-heading} Create a stack on the board. @@ -641,7 +641,7 @@ Create a stack on the board. Returns the created stack. -#### Update stack +#### Update stack {.ep-heading} Update a stack by ID. @@ -665,7 +665,7 @@ Update a stack by ID. Returns the updated stack. -#### Delete stack +#### Delete stack {.ep-heading} Delete a stack by ID. @@ -684,7 +684,7 @@ Returns the deleted stack. The `deletedAt`-key contains the UNIX timestamp at de ### Cards -#### Get card +#### Get card {.ep-heading} Get a card by ID. @@ -724,7 +724,7 @@ Get a card by ID. } ``` -#### Create card +#### Create card {.ep-heading} Crreate a card on the board stack. @@ -773,7 +773,7 @@ Crreate a card on the board stack. } ``` -#### Update card +#### Update card {.ep-heading} Update a card by ID. @@ -817,7 +817,7 @@ Update a card by ID. Returns the updated card. -#### Delete card +#### Delete card {.ep-heading} Delete a card by ID. @@ -835,7 +835,7 @@ Delete a card by ID. Returns the deleted card. The `deletedAt`-key contains the UNIX timestamp at deletion. -#### Assign label +#### Assign label {.ep-heading} Assign a board label to a card. @@ -859,7 +859,7 @@ Assign a board label to a card. Returns an empty response. -#### Unassign label +#### Unassign label {.ep-heading} Unassign a board label from a card. @@ -883,7 +883,7 @@ Unassign a board label from a card. Returns an empty response. -#### Assign user +#### Assign user {.ep-heading} Assign a board user to a card. @@ -917,7 +917,7 @@ Assign a board user to a card. } ``` -#### Unassign user +#### Unassign user {.ep-heading} Unassing a user from a card. @@ -941,7 +941,7 @@ Unassing a user from a card. Returns the removed user assignment. -#### Move card +#### Move card {.ep-heading} Update the order and/or the stack of the card. @@ -966,7 +966,7 @@ Update the order and/or the stack of the card. Returns a list of stack cards in the updated order. -#### Archive card +#### Archive card {.ep-heading} Archive a card. @@ -984,7 +984,7 @@ Archive a card. Returns the archived card. -#### Unarchive card +#### Unarchive card {.ep-heading} Unarchive a card. @@ -1004,7 +1004,7 @@ Returns the unarchived card. ### Labels -#### Get label +#### Get label {.ep-heading} Get a label by ID. @@ -1029,7 +1029,7 @@ Get a label by ID. } ``` -#### Create label +#### Create label {.ep-heading} Create a label. @@ -1062,7 +1062,7 @@ Create a label. } ``` -#### Update label +#### Update label {.ep-heading} Update a label by ID. @@ -1088,7 +1088,7 @@ Update a label by ID. Returns the updated label. -#### Delete label +#### Delete label {.ep-heading} Delete a label by ID. @@ -1107,7 +1107,7 @@ Returns the deleted label. ### Attachments -#### List attachments +#### List attachments {.ep-heading} Get a list of all card attachments. When api-Version `v1.0` is used, then this endpoint returns only attachments of type `deck_file`. @@ -1150,7 +1150,7 @@ attachments of type `deck_file`. ``` -#### Get attachment +#### Get attachment {.ep-heading} Get a card attachment by ID. @@ -1174,7 +1174,7 @@ v1.1 Returns the card attachment. -#### Upload attachment +#### Upload attachment {.ep-heading} Upload a card attachment. @@ -1202,7 +1202,7 @@ Upload a card attachment. Returns the card attachement. -#### Update attachment +#### Update attachment {.ep-heading} Update a card attachment by ID. @@ -1235,7 +1235,7 @@ For now only `deck_file` is supported as an attachment type. Returns the updated card attachment. -#### Delete attachment +#### Delete attachment {.ep-heading} Delete a card attachment by ID. @@ -1259,7 +1259,7 @@ v1.1 Returns the deleted attachment. -#### Restore attachment +#### Restore attachment {.ep-heading} Restore a deleted card attachment by ID. @@ -1285,7 +1285,7 @@ Returns the restored attachment. ### Import API -#### Get Systems +#### Get Systems {.ep-heading} Get the allowed import systems. @@ -1299,7 +1299,7 @@ Get the allowed import systems. ] ``` -#### Get System Schema +#### Get System Schema {.ep-heading} Get a system schema. @@ -1317,7 +1317,7 @@ Get a system schema. {} ``` -#### Import board +#### Import board {.ep-heading} Import a board from another system. @@ -1344,7 +1344,7 @@ This has the benefit that both the web UI as well as external integrations can u Deck stores user and app configuration values globally and per board. The GET endpoint allows to fetch the current global configuration while board settings will be exposed through the board element on the regular API endpoints. -#### Get app configuration +#### Get app configuration {.ep-heading} Get the configuration of the deck app. @@ -1383,7 +1383,7 @@ Get the configuration of the deck app. ``` -#### Set config value +#### Set config value {.ep-heading} Set a configuration value by key. @@ -1426,7 +1426,7 @@ curl -X POST 'https://admin:admin@nextcloud.local/ocs/v2.php/apps/deck/api/v1.0/ ### Comments -#### List comments +#### List comments {.ep-heading} List comments for a card. @@ -1518,7 +1518,7 @@ In case a comment is marked as a reply to another comment object, the parent com ] ``` -#### Create comment +#### Create comment {.ep-heading} Create comment for a card. @@ -1573,7 +1573,7 @@ A list of comments will be provided under the `ocs.data` key. If no or no more c } ``` -#### Update comment +#### Update comment {.ep-heading} Update a card comment by ID. @@ -1624,7 +1624,7 @@ A list of comments will be provided under the `ocs.data` key. If no or no more c } ``` -#### Delete comment +#### Delete comment {.ep-heading} Delete a card comment by ID. @@ -1664,7 +1664,7 @@ A list of comments will be provided under the `ocs.data` key. If no or no more c ### Sessions -#### Creates session +#### Creates session {.ep-heading} Create a session. @@ -1700,7 +1700,7 @@ curl -X PUT 'https://admin:admin@nextcloud/ocs/v2.php/apps/deck/api/v1.0/session } ``` -#### Sync session +#### Sync session {.ep-heading} Notify the server that the session is still open: @@ -1736,7 +1736,7 @@ curl -X POST 'https://admin:admin@nextcloud/ocs/v2.php/apps/deck/api/v1.0/sessio } ``` -#### Close session +#### Close session {.ep-heading} Close a session. diff --git a/docs/extra.css b/docs/extra.css index 325678bc6b..d077760912 100644 --- a/docs/extra.css +++ b/docs/extra.css @@ -18,3 +18,8 @@ .headerlink { font-size: 1.125rem !important; } + +.ep-heading { + margin-block-start: 3rem; + border-bottom: 2px solid grey; +} diff --git a/mkdocs.yml b/mkdocs.yml index dcb695bef1..4041ecdb42 100644 --- a/mkdocs.yml +++ b/mkdocs.yml @@ -17,5 +17,6 @@ nav: - Implement import: implement-import.md - Class diagram: import-class-diagram.md markdown_extensions: + - attr_list - toc: permalink: "#" From 6b589c5f9f58c4b0709cb8d5b4f5816eaccbf538 Mon Sep 17 00:00:00 2001 From: Viktor Diezel Date: Thu, 7 Aug 2025 00:12:17 +0200 Subject: [PATCH 15/30] docs: (opinionated) style endpoint URL Signed-off-by: Viktor Diezel --- docs/API.md | 106 ++++++++++++++++++++++++------------------------- docs/extra.css | 4 ++ 2 files changed, 57 insertions(+), 53 deletions(-) diff --git a/docs/API.md b/docs/API.md index a73745e7d5..e7cda6ce1d 100644 --- a/docs/API.md +++ b/docs/API.md @@ -155,7 +155,7 @@ This API version has become available with **Deck 1.3.0**. Get a list of all user boards. -`GET /boards` +`GET /boards`{.ep-path} ##### Headers @@ -205,7 +205,7 @@ The board list endpoint supports setting an `If-Modified-Since` header to limit Create a new board. The user's ability to create new boards can be disabled by the administrator. For checking this before, see the `canCreateBoards` value in the [Nextcloud capabilties](./API-Nextcloud.md). -`POST /boards` +`POST /boards`{.ep-path} ##### Request body @@ -281,7 +281,7 @@ Create a new board. The user's ability to create new boards can be disabled by t Get a board by ID. -`GET /boards/{boardId}` +`GET /boards/{boardId}`{.ep-path} ##### Request parameters @@ -354,7 +354,7 @@ Get a board by ID. Update a board by ID. -`PUT /boards/{boardId}` +`PUT /boards/{boardId}`{.ep-path} ##### Request parameters @@ -386,7 +386,7 @@ Returns the updated board. Delete a board by ID. -`DELETE /boards/{boardId}` +`DELETE /boards/{boardId}`{.ep-path} ##### Request parameters @@ -402,7 +402,7 @@ Returns the deleted board. The `deletedAt`-key contains the UNIX timestamp at de Restore a deleted board by ID. -`POST /boards/{boardId}/undo_delete` +`POST /boards/{boardId}/undo_delete`{.ep-path} ##### Request parameters @@ -418,7 +418,7 @@ Returns the restored board. Clone a board by ID. -`POST /boards/{boardId}/clone` +`POST /boards/{boardId}/clone`{.ep-path} Creates a copy of the board. @@ -445,7 +445,7 @@ Returns the restored board. Create an ACL for a board. -`POST /boards/{boardId}/acl` +`POST /boards/{boardId}/acl`{.ep-path} ##### Request parameters @@ -491,7 +491,7 @@ Create an ACL for a board. Update an ACL by ID. -`PUT /boards/{boardId}/acl/{aclId}` +`PUT /boards/{boardId}/acl/{aclId}`{.ep-path} ##### Request parameters @@ -516,7 +516,7 @@ Returns the updated ACL. Delete an ACL by ID. -`DELETE /boards/{boardId}/acl/{aclId}` +`DELETE /boards/{boardId}/acl/{aclId}`{.ep-path} ##### Request parameters @@ -535,7 +535,7 @@ Returns the deleted ACL. Get a list of all board stacks. -`GET /boards/{boardId}/stacks` +`GET /boards/{boardId}/stacks`{.ep-path} ##### Headers @@ -567,7 +567,7 @@ The board list endpoint supports setting an `If-Modified-Since` header to limit Get a list of archived stacks -`GET /boards/{boardId}/stacks/archived` +`GET /boards/{boardId}/stacks/archived`{.ep-path} ##### Request parameters @@ -595,7 +595,7 @@ Get a list of archived stacks Get a stack by ID. -`GET /boards/{boardId}/stacks/{stackId}` +`GET /boards/{boardId}/stacks/{stackId}`{.ep-path} ##### Request parameters @@ -622,7 +622,7 @@ Get a stack by ID. Create a stack on the board. -`POST /boards/{boardId}/stacks` +`POST /boards/{boardId}/stacks`{.ep-path} ##### Request parameters @@ -645,7 +645,7 @@ Returns the created stack. Update a stack by ID. -`PUT /boards/{boardId}/stacks/{stackId}` +`PUT /boards/{boardId}/stacks/{stackId}`{.ep-path} ##### Request parameters @@ -669,7 +669,7 @@ Returns the updated stack. Delete a stack by ID. -`DELETE /boards/{boardId}/stacks/{stackId}` +`DELETE /boards/{boardId}/stacks/{stackId}`{.ep-path} ##### Request parameters @@ -688,7 +688,7 @@ Returns the deleted stack. The `deletedAt`-key contains the UNIX timestamp at de Get a card by ID. -`GET /boards/{boardId}/stacks/{stackId}/cards/{cardId}` +`GET /boards/{boardId}/stacks/{stackId}/cards/{cardId}`{.ep-path} ##### Request parameters @@ -728,7 +728,7 @@ Get a card by ID. Crreate a card on the board stack. -`POST /boards/{boardId}/stacks/{stackId}/cards` +`POST /boards/{boardId}/stacks/{stackId}/cards`{.ep-path} ##### Request parameters @@ -777,7 +777,7 @@ Crreate a card on the board stack. Update a card by ID. -`PUT /boards/{boardId}/stacks/{stackId}/cards/{cardId}` +`PUT /boards/{boardId}/stacks/{stackId}/cards/{cardId}`{.ep-path} ##### Request parameters @@ -821,7 +821,7 @@ Returns the updated card. Delete a card by ID. -`DELETE /boards/{boardId}/stacks/{stackId}/cards/{cardId}` +`DELETE /boards/{boardId}/stacks/{stackId}/cards/{cardId}`{.ep-path} ##### Request parameters @@ -839,7 +839,7 @@ Returns the deleted card. The `deletedAt`-key contains the UNIX timestamp at del Assign a board label to a card. -`PUT /boards/{boardId}/stacks/{stackId}/cards/{cardId}/assignLabel` +`PUT /boards/{boardId}/stacks/{stackId}/cards/{cardId}/assignLabel`{.ep-path} ##### Request parameters @@ -863,7 +863,7 @@ Returns an empty response. Unassign a board label from a card. -`PUT /boards/{boardId}/stacks/{stackId}/cards/{cardId}/removeLabel` +`PUT /boards/{boardId}/stacks/{stackId}/cards/{cardId}/removeLabel`{.ep-path} ##### Request parameters @@ -887,7 +887,7 @@ Returns an empty response. Assign a board user to a card. -`PUT /boards/{boardId}/stacks/{stackId}/cards/{cardId}/assignUser` +`PUT /boards/{boardId}/stacks/{stackId}/cards/{cardId}/assignUser`{.ep-path} ##### Request parameters @@ -921,7 +921,7 @@ Assign a board user to a card. Unassing a user from a card. -`PUT /boards/{boardId}/stacks/{stackId}/cards/{cardId}/unassignUser` +`PUT /boards/{boardId}/stacks/{stackId}/cards/{cardId}/unassignUser`{.ep-path} ##### Request parameters @@ -945,7 +945,7 @@ Returns the removed user assignment. Update the order and/or the stack of the card. -`PUT /boards/{boardId}/stacks/{stackId}/cards/{cardId}/reorder` +`PUT /boards/{boardId}/stacks/{stackId}/cards/{cardId}/reorder`{.ep-path} ##### Request parameters @@ -970,7 +970,7 @@ Returns a list of stack cards in the updated order. Archive a card. -`PUT /boards/{boardId}/stacks/{stackId}/cards/{cardId}/archive` +`PUT /boards/{boardId}/stacks/{stackId}/cards/{cardId}/archive`{.ep-path} ##### Request parameters @@ -988,7 +988,7 @@ Returns the archived card. Unarchive a card. -`PUT /boards/{boardId}/stacks/{stackId}/cards/{cardId}/unarchive` +`PUT /boards/{boardId}/stacks/{stackId}/cards/{cardId}/unarchive`{.ep-path} ##### Request parameters @@ -1008,7 +1008,7 @@ Returns the unarchived card. Get a label by ID. -`GET /boards/{boardId}/labels/{labelId}` +`GET /boards/{boardId}/labels/{labelId}`{.ep-path} ##### Request parameters @@ -1033,7 +1033,7 @@ Get a label by ID. Create a label. -`POST /boards/{boardId}/labels` +`POST /boards/{boardId}/labels`{.ep-path} ##### Request parameters @@ -1066,7 +1066,7 @@ Create a label. Update a label by ID. -`PUT /boards/{boardId}/labels/{labelId}` +`PUT /boards/{boardId}/labels/{labelId}`{.ep-path} ##### Request parameters @@ -1092,7 +1092,7 @@ Returns the updated label. Delete a label by ID. -`DELETE /boards/{boardId}/labels/{labelId}` +`DELETE /boards/{boardId}/labels/{labelId}`{.ep-path} ##### Request parameters @@ -1112,7 +1112,7 @@ Returns the deleted label. Get a list of all card attachments. When api-Version `v1.0` is used, then this endpoint returns only attachments of type `deck_file`. -`GET /boards/{boardId}/stacks/{stackId}/cards/{cardId}/attachments` +`GET /boards/{boardId}/stacks/{stackId}/cards/{cardId}/attachments`{.ep-path} ##### Request parameters @@ -1155,10 +1155,10 @@ attachments of type `deck_file`. Get a card attachment by ID. v1.0 -`GET /boards/{boardId}/stacks/{stackId}/cards/{cardId}/attachments/{attachmentId}` +`GET /boards/{boardId}/stacks/{stackId}/cards/{cardId}/attachments/{attachmentId}`{.ep-path} v1.1 -`GET /boards/{boardId}/stacks/{stackId}/cards/{cardId}/attachments/{type}/{attachmentId}` +`GET /boards/{boardId}/stacks/{stackId}/cards/{cardId}/attachments/{type}/{attachmentId}`{.ep-path} ##### Request parameters @@ -1178,7 +1178,7 @@ Returns the card attachment. Upload a card attachment. -`POST /boards/{boardId}/stacks/{stackId}/cards/{cardId}/attachments` +`POST /boards/{boardId}/stacks/{stackId}/cards/{cardId}/attachments`{.ep-path} ##### Request parameters @@ -1207,10 +1207,10 @@ Returns the card attachement. Update a card attachment by ID. v1.0 -`PUT /boards/{boardId}/stacks/{stackId}/cards/{cardId}/attachments/{attachmentId}` +`PUT /boards/{boardId}/stacks/{stackId}/cards/{cardId}/attachments/{attachmentId}`{.ep-path} v1.1 -`PUT /boards/{boardId}/stacks/{stackId}/cards/{cardId}/attachments/{type}/{attachmentId}` +`PUT /boards/{boardId}/stacks/{stackId}/cards/{cardId}/attachments/{type}/{attachmentId}`{.ep-path} ##### Request parameters @@ -1240,10 +1240,10 @@ Returns the updated card attachment. Delete a card attachment by ID. v1.0 -`DELETE /boards/{boardId}/stacks/{stackId}/cards/{cardId}/attachments/{attachmentId}` +`DELETE /boards/{boardId}/stacks/{stackId}/cards/{cardId}/attachments/{attachmentId}`{.ep-path} v1.1 -`DELETE /boards/{boardId}/stacks/{stackId}/cards/{cardId}/attachments/{type}/{attachmentId}` +`DELETE /boards/{boardId}/stacks/{stackId}/cards/{cardId}/attachments/{type}/{attachmentId}`{.ep-path} ##### Request parameters @@ -1264,10 +1264,10 @@ Returns the deleted attachment. Restore a deleted card attachment by ID. v1.0 -`PUT /boards/{boardId}/stacks/{stackId}/cards/{cardId}/attachments/{attachmentId}/restore` +`PUT /boards/{boardId}/stacks/{stackId}/cards/{cardId}/attachments/{attachmentId}/restore`{.ep-path} v1.1 -`PUT /boards/{boardId}/stacks/{stackId}/cards/{cardId}/attachments/{type}/{attachmentId}/restore` +`PUT /boards/{boardId}/stacks/{stackId}/cards/{cardId}/attachments/{type}/{attachmentId}/restore`{.ep-path} ##### Request parameters @@ -1289,7 +1289,7 @@ Returns the restored attachment. Get the allowed import systems. -`GET /boards/import/getSystems` +`GET /boards/import/getSystems`{.ep-path} ##### Response @@ -1303,7 +1303,7 @@ Get the allowed import systems. Get a system schema. -`GET /boards/import/config/system/{system}` +`GET /boards/import/config/system/{system}`{.ep-path} ##### Request parameters @@ -1321,7 +1321,7 @@ Get a system schema. Import a board from another system. -`POST /boards/import` +`POST /boards/import`{.ep-path} ##### Request parameters @@ -1348,7 +1348,7 @@ Deck stores user and app configuration values globally and per board. The GET en Get the configuration of the deck app. -`GET /api/v1.0/config` +`GET /api/v1.0/config`{.ep-path} ##### Response @@ -1387,7 +1387,7 @@ Get the configuration of the deck app. Set a configuration value by key. -`POST /api/v1.0/config/{id}/{key}` +`POST /api/v1.0/config/{id}/{key}`{.ep-path} ##### Request parameters @@ -1430,7 +1430,7 @@ curl -X POST 'https://admin:admin@nextcloud.local/ocs/v2.php/apps/deck/api/v1.0/ List comments for a card. -`GET /cards/{cardId}/comments` +`GET /cards/{cardId}/comments`{.ep-path} ##### Request parameters @@ -1522,7 +1522,7 @@ In case a comment is marked as a reply to another comment object, the parent com Create comment for a card. -`POST /cards/{cardId}/comments` +`POST /cards/{cardId}/comments`{.ep-path} ##### Request parameters @@ -1577,7 +1577,7 @@ A list of comments will be provided under the `ocs.data` key. If no or no more c Update a card comment by ID. -`PUT /cards/{cardId}/comments/{commentId}` +`PUT /cards/{cardId}/comments/{commentId}`{.ep-path} ##### Request parameters @@ -1628,7 +1628,7 @@ A list of comments will be provided under the `ocs.data` key. If no or no more c Delete a card comment by ID. -`DELETE /cards/{cardId}/comments/{commentId}` +`DELETE /cards/{cardId}/comments/{commentId}`{.ep-path} ##### Request parameters @@ -1668,7 +1668,7 @@ A list of comments will be provided under the `ocs.data` key. If no or no more c Create a session. -`PUT /session/create` +`PUT /session/create`{.ep-path} ##### Request parameters @@ -1704,7 +1704,7 @@ curl -X PUT 'https://admin:admin@nextcloud/ocs/v2.php/apps/deck/api/v1.0/session Notify the server that the session is still open: -`POST /session/sync` +`POST /session/sync`{.ep-path} ##### Request body @@ -1740,7 +1740,7 @@ curl -X POST 'https://admin:admin@nextcloud/ocs/v2.php/apps/deck/api/v1.0/sessio Close a session. -`POST /session/close` +`POST /session/close`{.ep-path} ##### Request body diff --git a/docs/extra.css b/docs/extra.css index d077760912..d927eb11ab 100644 --- a/docs/extra.css +++ b/docs/extra.css @@ -23,3 +23,7 @@ margin-block-start: 3rem; border-bottom: 2px solid grey; } + +.ep-path { + display: block; +} From 9dfdbcb1a2cd5955163c2fc1fe92b1e4f1858b0d Mon Sep 17 00:00:00 2001 From: Viktor Diezel Date: Thu, 7 Aug 2025 00:13:23 +0200 Subject: [PATCH 16/30] docs: fix wrong enum value for attachment type Signed-off-by: Viktor Diezel --- docs/API.md | 8 ++++---- 1 file changed, 4 insertions(+), 4 deletions(-) diff --git a/docs/API.md b/docs/API.md index e7cda6ce1d..5c1907c580 100644 --- a/docs/API.md +++ b/docs/API.md @@ -1168,7 +1168,7 @@ v1.1 | stackId | Integer | The id of the stack the attachment belongs to | | cardId | Integer | The id of the card the attachment belongs to | | attachmentId | Integer | The id of the attachment | -| type | String | `file` \| `deck_app` | +| type | String | `file` \| `deck_file` | ##### Response @@ -1220,7 +1220,7 @@ v1.1 | stackId | Integer | The id of the stack the attachment belongs to | | cardId | Integer | The id of the card the attachment belongs to | | attachmentId | Integer | The id of the attachment | -| type | String | `file` \| `deck_app` | +| type | String | `file` \| `deck_file` | ##### Request body @@ -1253,7 +1253,7 @@ v1.1 | stackId | Integer | The id of the stack the attachment belongs to | | cardId | Integer | The id of the card the attachment belongs to | | attachmentId | Integer | The id of the attachment | -| type | String | `file` \| `deck_app` | +| type | String | `file` \| `deck_file` | ##### Response @@ -1277,7 +1277,7 @@ v1.1 | stackId | Integer | The id of the stack the attachment belongs to | | cardId | Integer | The id of the card the attachment belongs to | | attachmentId | Integer | The id of the attachment | -| type | String | `file` \| `deck_app` | +| type | String | `file` \| `deck_file` | ##### Response From 8570f8d88537feee18864204b9c40c5f7053653b Mon Sep 17 00:00:00 2001 From: Viktor Diezel Date: Thu, 7 Aug 2025 08:04:19 +0200 Subject: [PATCH 17/30] docs: minor fixes of request parameters Signed-off-by: Viktor Diezel --- docs/API.md | 12 +++++++----- 1 file changed, 7 insertions(+), 5 deletions(-) diff --git a/docs/API.md b/docs/API.md index 5c1907c580..9c6e423d1b 100644 --- a/docs/API.md +++ b/docs/API.md @@ -392,7 +392,7 @@ Delete a board by ID. | Parameter | Type | Description | | --------- | ------- | ---------------------------- | -| boardId | Integer | The id of the board to fetch | +| boardId | Integer | The id of the board to delete | ##### Response @@ -422,6 +422,8 @@ Clone a board by ID. Creates a copy of the board. +##### Request parameters + | Parameter | Type | Description | | --------- | ------- | ---------------------------- | | boardId | Integer | The id of the board | @@ -508,7 +510,7 @@ Update an ACL by ID. | permissionShare | Bool | Setting if the participant has sharing permissions | | permissionManage | Bool | Setting if the participant has management permissions | -#### Response {.ep-heading} +##### Response Returns the updated ACL. @@ -796,9 +798,9 @@ Update a card by ID. | type | String | Type of the card (for later use) use 'plain' for now | | owner | String | The user that owns the card | | order | Integer | Order for sorting the stacks | -| duedate | timestamp | The ISO-8601 formatted duedate of the card or null | +| duedate | timestamp \| null | The ISO-8601 formatted duedate of the card or null | | archived | bool | Whether the card is archived or not | -| done | timestamp\|null | The ISO-8601 formatted date when the card is marked as done (optional, null indicates undone state) | +| done | timestamp \| null | _(optional)_ The ISO-8601 formatted date when the card is marked as done (null indicates undone state) | ```json { @@ -1530,7 +1532,7 @@ Create comment for a card. | --------- | ------- | --------------------------------------- | | cardId | Integer | The id of the card | | message | String | The message of the comment, maximum length is limited to 1000 characters | -| parentId | Integer | _(optional)_ The start offset used for pagination, defaults to null | +| parentId | Integer \| null | _(optional)_ The id of the parent comment (when replying), defaults to null | Mentions will be parsed by the server. The server will return a list of mentions in the response to this request as shown below. From 9ddec3ff0f4ca76e9225605bdb591deff40f2189 Mon Sep 17 00:00:00 2001 From: Viktor Diezel Date: Thu, 7 Aug 2025 08:06:40 +0200 Subject: [PATCH 18/30] docs: rename request paramaters to path parameters and introduce query string parameters Signed-off-by: Viktor Diezel --- docs/API.md | 88 ++++++++++++++++++++++++++--------------------------- 1 file changed, 44 insertions(+), 44 deletions(-) diff --git a/docs/API.md b/docs/API.md index 9c6e423d1b..e0eb8214fe 100644 --- a/docs/API.md +++ b/docs/API.md @@ -161,7 +161,7 @@ Get a list of all user boards. The board list endpoint supports setting an `If-Modified-Since` header to limit the results to entities that are changed after the provided time. -##### Request parameters +##### Query string parameters | Parameter | Type | Description | | --------- | ------- | ---------------------------- | @@ -283,7 +283,7 @@ Get a board by ID. `GET /boards/{boardId}`{.ep-path} -##### Request parameters +##### Path parameters | Parameter | Type | Description | | --------- | ------- | ---------------------------- | @@ -356,7 +356,7 @@ Update a board by ID. `PUT /boards/{boardId}`{.ep-path} -##### Request parameters +##### Path parameters | Parameter | Type | Description | | --------- | ------ | ---------------------------------------------------- | @@ -388,7 +388,7 @@ Delete a board by ID. `DELETE /boards/{boardId}`{.ep-path} -##### Request parameters +##### Path parameters | Parameter | Type | Description | | --------- | ------- | ---------------------------- | @@ -404,7 +404,7 @@ Restore a deleted board by ID. `POST /boards/{boardId}/undo_delete`{.ep-path} -##### Request parameters +##### Path parameters | Parameter | Type | Description | | --------- | ------- | ---------------------------- | @@ -422,7 +422,7 @@ Clone a board by ID. Creates a copy of the board. -##### Request parameters +##### Path parameters | Parameter | Type | Description | | --------- | ------- | ---------------------------- | @@ -449,7 +449,7 @@ Create an ACL for a board. `POST /boards/{boardId}/acl`{.ep-path} -##### Request parameters +##### Path parameters | Parameter | Type | Description | | --------- | ------- | ---------------------------- | @@ -495,7 +495,7 @@ Update an ACL by ID. `PUT /boards/{boardId}/acl/{aclId}`{.ep-path} -##### Request parameters +##### Path parameters | Parameter | Type | Description | | --------- | ------- | ---------------------------- | @@ -520,7 +520,7 @@ Delete an ACL by ID. `DELETE /boards/{boardId}/acl/{aclId}`{.ep-path} -##### Request parameters +##### Path parameters | Parameter | Type | Description | | --------- | ------- | ---------------------------- | @@ -543,7 +543,7 @@ Get a list of all board stacks. The board list endpoint supports setting an `If-Modified-Since` header to limit the results to entities that are changed after the provided time. -##### Request parameters +##### Path parameters | Parameter | Type | Description | | --------- | ------- | ---------------------------- | @@ -571,7 +571,7 @@ Get a list of archived stacks `GET /boards/{boardId}/stacks/archived`{.ep-path} -##### Request parameters +##### Path parameters | Parameter | Type | Description | | --------- | ------- | ---------------------------- | @@ -599,7 +599,7 @@ Get a stack by ID. `GET /boards/{boardId}/stacks/{stackId}`{.ep-path} -##### Request parameters +##### Path parameters | Parameter | Type | Description | | --------- | ------- | ---------------------------------------- | @@ -626,7 +626,7 @@ Create a stack on the board. `POST /boards/{boardId}/stacks`{.ep-path} -##### Request parameters +##### Path parameters | Parameter | Type | Description | | --------- | ------- | ---------------------------- | @@ -649,7 +649,7 @@ Update a stack by ID. `PUT /boards/{boardId}/stacks/{stackId}`{.ep-path} -##### Request parameters +##### Path parameters | Parameter | Type | Description | | --------- | ------- | ---------------------------------------- | @@ -673,7 +673,7 @@ Delete a stack by ID. `DELETE /boards/{boardId}/stacks/{stackId}`{.ep-path} -##### Request parameters +##### Path parameters | Parameter | Type | Description | | --------- | ------- | ---------------------------------------- | @@ -692,7 +692,7 @@ Get a card by ID. `GET /boards/{boardId}/stacks/{stackId}/cards/{cardId}`{.ep-path} -##### Request parameters +##### Path parameters | Parameter | Type | Description | | --------- | ------- | --------------------------------------- | @@ -732,7 +732,7 @@ Crreate a card on the board stack. `POST /boards/{boardId}/stacks/{stackId}/cards`{.ep-path} -##### Request parameters +##### Path parameters | Parameter | Type | Description | | --------- | ------- | --------------------------------------- | @@ -781,7 +781,7 @@ Update a card by ID. `PUT /boards/{boardId}/stacks/{stackId}/cards/{cardId}`{.ep-path} -##### Request parameters +##### Path parameters | Parameter | Type | Description | | --------- | ------- | --------------------------------------- | @@ -825,7 +825,7 @@ Delete a card by ID. `DELETE /boards/{boardId}/stacks/{stackId}/cards/{cardId}`{.ep-path} -##### Request parameters +##### Path parameters | Parameter | Type | Description | | --------- | ------- | --------------------------------------- | @@ -843,7 +843,7 @@ Assign a board label to a card. `PUT /boards/{boardId}/stacks/{stackId}/cards/{cardId}/assignLabel`{.ep-path} -##### Request parameters +##### Path parameters | Parameter | Type | Description | | --------- | ------- | --------------------------------------- | @@ -867,7 +867,7 @@ Unassign a board label from a card. `PUT /boards/{boardId}/stacks/{stackId}/cards/{cardId}/removeLabel`{.ep-path} -##### Request parameters +##### Path parameters | Parameter | Type | Description | | --------- | ------- | --------------------------------------- | @@ -891,7 +891,7 @@ Assign a board user to a card. `PUT /boards/{boardId}/stacks/{stackId}/cards/{cardId}/assignUser`{.ep-path} -##### Request parameters +##### Path parameters | Parameter | Type | Description | | --------- | ------- | --------------------------------------- | @@ -925,7 +925,7 @@ Unassing a user from a card. `PUT /boards/{boardId}/stacks/{stackId}/cards/{cardId}/unassignUser`{.ep-path} -##### Request parameters +##### Path parameters | Parameter | Type | Description | | --------- | ------- | --------------------------------------- | @@ -949,7 +949,7 @@ Update the order and/or the stack of the card. `PUT /boards/{boardId}/stacks/{stackId}/cards/{cardId}/reorder`{.ep-path} -##### Request parameters +##### Path parameters | Parameter | Type | Description | | --------- | ------- | --------------------------------------- | @@ -974,7 +974,7 @@ Archive a card. `PUT /boards/{boardId}/stacks/{stackId}/cards/{cardId}/archive`{.ep-path} -##### Request parameters +##### Path parameters | Parameter | Type | Description | | --------- | ------- | --------------------------------------- | @@ -992,7 +992,7 @@ Unarchive a card. `PUT /boards/{boardId}/stacks/{stackId}/cards/{cardId}/unarchive`{.ep-path} -##### Request parameters +##### Path parameters | Parameter | Type | Description | | --------- | ------- | --------------------------------------- | @@ -1012,7 +1012,7 @@ Get a label by ID. `GET /boards/{boardId}/labels/{labelId}`{.ep-path} -##### Request parameters +##### Path parameters | Parameter | Type | Description | | --------- | ------- | ---------------------------------------- | @@ -1037,7 +1037,7 @@ Create a label. `POST /boards/{boardId}/labels`{.ep-path} -##### Request parameters +##### Path parameters | Parameter | Type | Description | | --------- | ------- | ---------------------------------------- | @@ -1070,7 +1070,7 @@ Update a label by ID. `PUT /boards/{boardId}/labels/{labelId}`{.ep-path} -##### Request parameters +##### Path parameters | Parameter | Type | Description | | --------- | ------- | ---------------------------------------- | @@ -1096,7 +1096,7 @@ Delete a label by ID. `DELETE /boards/{boardId}/labels/{labelId}`{.ep-path} -##### Request parameters +##### Path parameters | Parameter | Type | Description | | --------- | ------- | ---------------------------------------- | @@ -1116,7 +1116,7 @@ attachments of type `deck_file`. `GET /boards/{boardId}/stacks/{stackId}/cards/{cardId}/attachments`{.ep-path} -##### Request parameters +##### Path parameters | Parameter | Type | Description | | --------- | ------- | --------------------------------------- | @@ -1162,7 +1162,7 @@ v1.0 v1.1 `GET /boards/{boardId}/stacks/{stackId}/cards/{cardId}/attachments/{type}/{attachmentId}`{.ep-path} -##### Request parameters +##### Path parameters | Parameter | Type | Description | | ------------ | ------- | --------------------------------------------- | @@ -1182,7 +1182,7 @@ Upload a card attachment. `POST /boards/{boardId}/stacks/{stackId}/cards/{cardId}/attachments`{.ep-path} -##### Request parameters +##### Path parameters | Parameter | Type | Description | | --------- | ------- | --------------------------------------------- | @@ -1214,7 +1214,7 @@ v1.0 v1.1 `PUT /boards/{boardId}/stacks/{stackId}/cards/{cardId}/attachments/{type}/{attachmentId}`{.ep-path} -##### Request parameters +##### Path parameters | Parameter | Type | Description | | ------------ | ------- | --------------------------------------------- | @@ -1247,7 +1247,7 @@ v1.0 v1.1 `DELETE /boards/{boardId}/stacks/{stackId}/cards/{cardId}/attachments/{type}/{attachmentId}`{.ep-path} -##### Request parameters +##### Path parameters | Parameter | Type | Description | | ------------ | ------- | --------------------------------------------- | @@ -1271,7 +1271,7 @@ v1.0 v1.1 `PUT /boards/{boardId}/stacks/{stackId}/cards/{cardId}/attachments/{type}/{attachmentId}/restore`{.ep-path} -##### Request parameters +##### Path parameters | Parameter | Type | Description | | ------------ | ------- | --------------------------------------------- | @@ -1307,7 +1307,7 @@ Get a system schema. `GET /boards/import/config/system/{system}`{.ep-path} -##### Request parameters +##### Path parameters | Parameter | Type | Description | | ------------ | ------- | --------------------------------------------- | @@ -1325,7 +1325,7 @@ Import a board from another system. `POST /boards/import`{.ep-path} -##### Request parameters +##### Path parameters | Parameter | Type | Description | | ------------ | ------- | --------------------------------------------- | @@ -1391,7 +1391,7 @@ Set a configuration value by key. `POST /api/v1.0/config/{id}/{key}`{.ep-path} -##### Request parameters +##### Path parameters | Parameter | Type | Description | | --------- | ------- | --------------------------------------- | @@ -1434,7 +1434,7 @@ List comments for a card. `GET /cards/{cardId}/comments`{.ep-path} -##### Request parameters +##### Path parameters | Parameter | Type | Description | | --------- | ------- | --------------------------------------- | @@ -1526,7 +1526,7 @@ Create comment for a card. `POST /cards/{cardId}/comments`{.ep-path} -##### Request parameters +##### Path parameters | Parameter | Type | Description | | --------- | ------- | --------------------------------------- | @@ -1581,7 +1581,7 @@ Update a card comment by ID. `PUT /cards/{cardId}/comments/{commentId}`{.ep-path} -##### Request parameters +##### Path parameters | Parameter | Type | Description | | --------- | ------- | --------------------------------------- | @@ -1632,7 +1632,7 @@ Delete a card comment by ID. `DELETE /cards/{cardId}/comments/{commentId}`{.ep-path} -##### Request parameters +##### Path parameters | Parameter | Type | Description | | --------- | ------- | --------------------------------------- | @@ -1672,7 +1672,7 @@ Create a session. `PUT /session/create`{.ep-path} -##### Request parameters +##### Path parameters | Parameter | Type | Description | | --------- | ------- | ---------------------------------------------------- | From 7c521c57eff1521bec88a735b4c94f54f511554e Mon Sep 17 00:00:00 2001 From: Viktor Diezel Date: Thu, 7 Aug 2025 08:33:30 +0200 Subject: [PATCH 19/30] docs: more consistent heading structure for endpoints Signed-off-by: Viktor Diezel --- docs/API.md | 166 +++++++++++++++++++++++++++++++++++++++++++++++----- 1 file changed, 151 insertions(+), 15 deletions(-) diff --git a/docs/API.md b/docs/API.md index e0eb8214fe..bb5646a46c 100644 --- a/docs/API.md +++ b/docs/API.md @@ -155,6 +155,8 @@ This API version has become available with **Deck 1.3.0**. Get a list of all user boards. +##### Path + `GET /boards`{.ep-path} ##### Headers @@ -205,6 +207,8 @@ The board list endpoint supports setting an `If-Modified-Since` header to limit Create a new board. The user's ability to create new boards can be disabled by the administrator. For checking this before, see the `canCreateBoards` value in the [Nextcloud capabilties](./API-Nextcloud.md). +##### Path + `POST /boards`{.ep-path} ##### Request body @@ -214,6 +218,8 @@ Create a new board. The user's ability to create new boards can be disabled by t | title | String | The title of the new board, maximum length is limited to 100 characters | | color | String | The hexadecimal color of the new board (e.g. FF0000) | +###### Example + ```json { "title": "Board title", @@ -281,6 +287,8 @@ Create a new board. The user's ability to create new boards can be disabled by t Get a board by ID. +##### Path + `GET /boards/{boardId}`{.ep-path} ##### Path parameters @@ -354,6 +362,8 @@ Get a board by ID. Update a board by ID. +##### Path + `PUT /boards/{boardId}`{.ep-path} ##### Path parameters @@ -370,6 +380,8 @@ Update a board by ID. | color | String | The hexadecimal color of the board (e.g. FF0000) | | archived | Bool | Whether or not this board should be archived. | +###### Example + ```json { "title": "Board title", @@ -386,6 +398,8 @@ Returns the updated board. Delete a board by ID. +##### Path + `DELETE /boards/{boardId}`{.ep-path} ##### Path parameters @@ -402,6 +416,8 @@ Returns the deleted board. The `deletedAt`-key contains the UNIX timestamp at de Restore a deleted board by ID. +##### Path + `POST /boards/{boardId}/undo_delete`{.ep-path} ##### Path parameters @@ -418,6 +434,8 @@ Returns the restored board. Clone a board by ID. +##### Path + `POST /boards/{boardId}/clone`{.ep-path} Creates a copy of the board. @@ -447,6 +465,8 @@ Returns the restored board. Create an ACL for a board. +##### Path + `POST /boards/{boardId}/acl`{.ep-path} ##### Path parameters @@ -493,6 +513,8 @@ Create an ACL for a board. Update an ACL by ID. +##### Path + `PUT /boards/{boardId}/acl/{aclId}`{.ep-path} ##### Path parameters @@ -518,6 +540,8 @@ Returns the updated ACL. Delete an ACL by ID. +##### Path + `DELETE /boards/{boardId}/acl/{aclId}`{.ep-path} ##### Path parameters @@ -537,6 +561,8 @@ Returns the deleted ACL. Get a list of all board stacks. +##### Path + `GET /boards/{boardId}/stacks`{.ep-path} ##### Headers @@ -569,6 +595,8 @@ The board list endpoint supports setting an `If-Modified-Since` header to limit Get a list of archived stacks +##### Path + `GET /boards/{boardId}/stacks/archived`{.ep-path} ##### Path parameters @@ -597,6 +625,8 @@ Get a list of archived stacks Get a stack by ID. +##### Path + `GET /boards/{boardId}/stacks/{stackId}`{.ep-path} ##### Path parameters @@ -624,6 +654,8 @@ Get a stack by ID. Create a stack on the board. +##### Path + `POST /boards/{boardId}/stacks`{.ep-path} ##### Path parameters @@ -647,6 +679,8 @@ Returns the created stack. Update a stack by ID. +##### Path + `PUT /boards/{boardId}/stacks/{stackId}`{.ep-path} ##### Path parameters @@ -671,6 +705,8 @@ Returns the updated stack. Delete a stack by ID. +##### Path + `DELETE /boards/{boardId}/stacks/{stackId}`{.ep-path} ##### Path parameters @@ -690,6 +726,8 @@ Returns the deleted stack. The `deletedAt`-key contains the UNIX timestamp at de Get a card by ID. +##### Path + `GET /boards/{boardId}/stacks/{stackId}/cards/{cardId}`{.ep-path} ##### Path parameters @@ -730,6 +768,8 @@ Get a card by ID. Crreate a card on the board stack. +##### Path + `POST /boards/{boardId}/stacks/{stackId}/cards`{.ep-path} ##### Path parameters @@ -779,6 +819,8 @@ Crreate a card on the board stack. Update a card by ID. +##### Path + `PUT /boards/{boardId}/stacks/{stackId}/cards/{cardId}`{.ep-path} ##### Path parameters @@ -823,6 +865,8 @@ Returns the updated card. Delete a card by ID. +##### Path + `DELETE /boards/{boardId}/stacks/{stackId}/cards/{cardId}`{.ep-path} ##### Path parameters @@ -841,6 +885,8 @@ Returns the deleted card. The `deletedAt`-key contains the UNIX timestamp at del Assign a board label to a card. +##### Path + `PUT /boards/{boardId}/stacks/{stackId}/cards/{cardId}/assignLabel`{.ep-path} ##### Path parameters @@ -865,6 +911,8 @@ Returns an empty response. Unassign a board label from a card. +##### Path + `PUT /boards/{boardId}/stacks/{stackId}/cards/{cardId}/removeLabel`{.ep-path} ##### Path parameters @@ -889,6 +937,8 @@ Returns an empty response. Assign a board user to a card. +##### Path + `PUT /boards/{boardId}/stacks/{stackId}/cards/{cardId}/assignUser`{.ep-path} ##### Path parameters @@ -923,6 +973,8 @@ Assign a board user to a card. Unassing a user from a card. +##### Path + `PUT /boards/{boardId}/stacks/{stackId}/cards/{cardId}/unassignUser`{.ep-path} ##### Path parameters @@ -947,6 +999,8 @@ Returns the removed user assignment. Update the order and/or the stack of the card. +##### Path + `PUT /boards/{boardId}/stacks/{stackId}/cards/{cardId}/reorder`{.ep-path} ##### Path parameters @@ -972,6 +1026,8 @@ Returns a list of stack cards in the updated order. Archive a card. +##### Path + `PUT /boards/{boardId}/stacks/{stackId}/cards/{cardId}/archive`{.ep-path} ##### Path parameters @@ -990,6 +1046,8 @@ Returns the archived card. Unarchive a card. +##### Path + `PUT /boards/{boardId}/stacks/{stackId}/cards/{cardId}/unarchive`{.ep-path} ##### Path parameters @@ -1010,6 +1068,8 @@ Returns the unarchived card. Get a label by ID. +##### Path + `GET /boards/{boardId}/labels/{labelId}`{.ep-path} ##### Path parameters @@ -1035,6 +1095,8 @@ Get a label by ID. Create a label. +##### Path + `POST /boards/{boardId}/labels`{.ep-path} ##### Path parameters @@ -1068,6 +1130,8 @@ Create a label. Update a label by ID. +##### Path + `PUT /boards/{boardId}/labels/{labelId}`{.ep-path} ##### Path parameters @@ -1094,6 +1158,8 @@ Returns the updated label. Delete a label by ID. +##### Path + `DELETE /boards/{boardId}/labels/{labelId}`{.ep-path} ##### Path parameters @@ -1114,6 +1180,8 @@ Returns the deleted label. Get a list of all card attachments. When api-Version `v1.0` is used, then this endpoint returns only attachments of type `deck_file`. +##### Path + `GET /boards/{boardId}/stacks/{stackId}/cards/{cardId}/attachments`{.ep-path} ##### Path parameters @@ -1157,9 +1225,13 @@ attachments of type `deck_file`. Get a card attachment by ID. v1.0 +##### Path + `GET /boards/{boardId}/stacks/{stackId}/cards/{cardId}/attachments/{attachmentId}`{.ep-path} v1.1 +##### Path + `GET /boards/{boardId}/stacks/{stackId}/cards/{cardId}/attachments/{type}/{attachmentId}`{.ep-path} ##### Path parameters @@ -1180,6 +1252,8 @@ Returns the card attachment. Upload a card attachment. +##### Path + `POST /boards/{boardId}/stacks/{stackId}/cards/{cardId}/attachments`{.ep-path} ##### Path parameters @@ -1209,9 +1283,13 @@ Returns the card attachement. Update a card attachment by ID. v1.0 +##### Path + `PUT /boards/{boardId}/stacks/{stackId}/cards/{cardId}/attachments/{attachmentId}`{.ep-path} v1.1 +##### Path + `PUT /boards/{boardId}/stacks/{stackId}/cards/{cardId}/attachments/{type}/{attachmentId}`{.ep-path} ##### Path parameters @@ -1242,9 +1320,13 @@ Returns the updated card attachment. Delete a card attachment by ID. v1.0 +##### Path + `DELETE /boards/{boardId}/stacks/{stackId}/cards/{cardId}/attachments/{attachmentId}`{.ep-path} v1.1 +##### Path + `DELETE /boards/{boardId}/stacks/{stackId}/cards/{cardId}/attachments/{type}/{attachmentId}`{.ep-path} ##### Path parameters @@ -1266,9 +1348,13 @@ Returns the deleted attachment. Restore a deleted card attachment by ID. v1.0 +##### Path + `PUT /boards/{boardId}/stacks/{stackId}/cards/{cardId}/attachments/{attachmentId}/restore`{.ep-path} v1.1 +##### Path + `PUT /boards/{boardId}/stacks/{stackId}/cards/{cardId}/attachments/{type}/{attachmentId}/restore`{.ep-path} ##### Path parameters @@ -1291,6 +1377,8 @@ Returns the restored attachment. Get the allowed import systems. +##### Path + `GET /boards/import/getSystems`{.ep-path} ##### Response @@ -1305,6 +1393,8 @@ Get the allowed import systems. Get a system schema. +##### Path + `GET /boards/import/config/system/{system}`{.ep-path} ##### Path parameters @@ -1323,6 +1413,8 @@ Get a system schema. Import a board from another system. +##### Path + `POST /boards/import`{.ep-path} ##### Path parameters @@ -1350,6 +1442,8 @@ Deck stores user and app configuration values globally and per board. The GET en Get the configuration of the deck app. +##### Path + `GET /api/v1.0/config`{.ep-path} ##### Response @@ -1389,6 +1483,8 @@ Get the configuration of the deck app. Set a configuration value by key. +##### Path + `POST /api/v1.0/config/{id}/{key}`{.ep-path} ##### Path parameters @@ -1399,7 +1495,7 @@ Set a configuration value by key. | key | String | The config key to set, prefixed with `board:{boardId}:` for board specific settings | | value | String | The value that should be stored for the config key | -###### Board configuration +###### Board configuration options | Key | Value | | --- | ----- | @@ -1408,11 +1504,19 @@ Set a configuration value by key. | cardDetailsInModal | Boolean | | cardIdBadge | Boolean | -##### Example request +###### Example -```json -curl -X POST 'https://admin:admin@nextcloud.local/ocs/v2.php/apps/deck/api/v1.0/config/calendar' -H 'Accept: application/json' -H "Content-Type: application/json" -H 'OCS-APIRequest: true' --data-raw '{"value":false}' +```bash +curl -X POST 'https://admin:admin@nextcloud.local/ocs/v2.php/apps/deck/api/v1.0/config/calendar' + -H 'Accept: application/json' + -H "Content-Type: application/json" + -H 'OCS-APIRequest: true' + --data-raw '{"value":false}' +``` +##### Response + +```json { "ocs": { "meta": { @@ -1423,7 +1527,6 @@ curl -X POST 'https://admin:admin@nextcloud.local/ocs/v2.php/apps/deck/api/v1.0/ "data": false } } - ``` ### Comments @@ -1432,6 +1535,8 @@ curl -X POST 'https://admin:admin@nextcloud.local/ocs/v2.php/apps/deck/api/v1.0/ List comments for a card. +##### Path + `GET /cards/{cardId}/comments`{.ep-path} ##### Path parameters @@ -1442,6 +1547,8 @@ List comments for a card. | limit | Integer | The maximum number of comments that should be returned, defaults to 20 | | offset | Integer | The start offset used for pagination, defaults to 0 | +###### Example + ```bash curl 'https://admin:admin@nextcloud/ocs/v2.php/apps/deck/api/v1.0/cards/12/comments' \ -H 'Accept: application/json' -H 'OCS-APIRequest: true' @@ -1524,6 +1631,8 @@ In case a comment is marked as a reply to another comment object, the parent com Create comment for a card. +##### Path + `POST /cards/{cardId}/comments`{.ep-path} ##### Path parameters @@ -1531,11 +1640,18 @@ Create comment for a card. | Parameter | Type | Description | | --------- | ------- | --------------------------------------- | | cardId | Integer | The id of the card | + +##### Request body + +| Parameter | Type | Description | +| --------- | ------- | --------------------------------------- | | message | String | The message of the comment, maximum length is limited to 1000 characters | -| parentId | Integer \| null | _(optional)_ The id of the parent comment (when replying), defaults to null | +| parentId | Integer \| null | The id of the parent comment (when replying) | Mentions will be parsed by the server. The server will return a list of mentions in the response to this request as shown below. +###### Example + ```bash curl -X POST 'https://admin:admin@nextcloud/ocs/v2.php/apps/deck/api/v1.0/cards/12/comments' \ -H 'Accept: application/json' -H 'OCS-APIRequest: true' @@ -1545,9 +1661,9 @@ curl -X POST 'https://admin:admin@nextcloud/ocs/v2.php/apps/deck/api/v1.0/cards/ ##### Response -A list of comments will be provided under the `ocs.data` key. If no or no more comments are available the list will be empty. +The created comment will be provided under the `ocs.data` key. -```bash +```json { "ocs": { "meta": { @@ -1577,7 +1693,9 @@ A list of comments will be provided under the `ocs.data` key. If no or no more c #### Update comment {.ep-heading} -Update a card comment by ID. +Update a card comment by ID. Updating comments is limited to the current user being the same as the comment author specified in the `actorId` of the comment. + +##### Path `PUT /cards/{cardId}/comments/{commentId}`{.ep-path} @@ -1587,11 +1705,16 @@ Update a card comment by ID. | --------- | ------- | --------------------------------------- | | cardId | Integer | The id of the card | | commentId | Integer | The id of the comment | + +##### Request body + +| Parameter | Type | Description | +| --------- | ------- | --------------------------------------- | | message | String | The message of the comment, maximum length is limited to 1000 characters | Mentions will be parsed by the server. The server will return a list of mentions in the response to this request as shown below. -Updating comments is limited to the current user being the same as the comment author specified in the `actorId` of the comment. +###### Example ```bash curl -X PUT 'https://admin:admin@nextcloud/ocs/v2.php/apps/deck/api/v1.0/cards/12/comments/123' \ @@ -1602,7 +1725,7 @@ curl -X PUT 'https://admin:admin@nextcloud/ocs/v2.php/apps/deck/api/v1.0/cards/1 ##### Response -A list of comments will be provided under the `ocs.data` key. If no or no more comments are available the list will be empty. +The updated comment will be provided under the `ocs.data` key. ```json { @@ -1628,7 +1751,9 @@ A list of comments will be provided under the `ocs.data` key. If no or no more c #### Delete comment {.ep-heading} -Delete a card comment by ID. +Delete a card comment by ID. Deleting comments is limited to the current user being the same as the comment author specified in the `actorId` of the comment. + +##### Path `DELETE /cards/{cardId}/comments/{commentId}`{.ep-path} @@ -1639,7 +1764,7 @@ Delete a card comment by ID. | cardId | Integer | The id of the card | | commentId | Integer | The id of the comment | -Deleting comments is limited to the current user being the same as the comment author specified in the `actorId` of the comment. +##### Example ```bash curl -X DELETE 'https://admin:admin@nextcloud/ocs/v2.php/apps/deck/api/v1.0/cards/12/comments/123' \ @@ -1670,14 +1795,18 @@ A list of comments will be provided under the `ocs.data` key. If no or no more c Create a session. +##### Path + `PUT /session/create`{.ep-path} -##### Path parameters +##### Request body | Parameter | Type | Description | | --------- | ------- | ---------------------------------------------------- | | boardId | Integer | The id of the opened board | +###### Example + ```bash curl -X PUT 'https://admin:admin@nextcloud/ocs/v2.php/apps/deck/api/v1.0/session/create' \ -H 'Accept: application/json' -H 'OCS-APIRequest: true' \ @@ -1704,7 +1833,9 @@ curl -X PUT 'https://admin:admin@nextcloud/ocs/v2.php/apps/deck/api/v1.0/session #### Sync session {.ep-heading} -Notify the server that the session is still open: +Notify the server that the session is still open. + +##### Path `POST /session/sync`{.ep-path} @@ -1715,6 +1846,7 @@ Notify the server that the session is still open: | boardId | Integer | The id of the opened board | | token | String | The session token from the /sessions/create response | +###### Example ```bash curl -X POST 'https://admin:admin@nextcloud/ocs/v2.php/apps/deck/api/v1.0/session/create' \ @@ -1742,6 +1874,8 @@ curl -X POST 'https://admin:admin@nextcloud/ocs/v2.php/apps/deck/api/v1.0/sessio Close a session. +##### Path + `POST /session/close`{.ep-path} ##### Request body @@ -1751,6 +1885,8 @@ Close a session. | boardId | Integer | The id of the opened board | | token | String | The session token from the /sessions/create response | +###### Example + ```bash curl -X POST 'https://admin:admin@nextcloud/ocs/v2.php/apps/deck/api/v1.0/session/close' \ -H 'Accept: application/json' -H 'OCS-APIRequest: true' \ From 0972f4c9ec4a3b1871985b51acd9a705d4b7d0dd Mon Sep 17 00:00:00 2001 From: Viktor Diezel Date: Thu, 7 Aug 2025 08:50:28 +0200 Subject: [PATCH 20/30] docs: fixes set config endpoint Signed-off-by: Viktor Diezel --- docs/API.md | 26 +++++++++++++++----------- 1 file changed, 15 insertions(+), 11 deletions(-) diff --git a/docs/API.md b/docs/API.md index bb5646a46c..b6fa469b5e 100644 --- a/docs/API.md +++ b/docs/API.md @@ -1485,24 +1485,19 @@ Set a configuration value by key. ##### Path -`POST /api/v1.0/config/{id}/{key}`{.ep-path} +`POST /api/v1.0/config/{key}`{.ep-path} ##### Path parameters | Parameter | Type | Description | | --------- | ------- | --------------------------------------- | -| id | Integer | The id of the board | -| key | String | The config key to set, prefixed with `board:{boardId}:` for board specific settings | -| value | String | The value that should be stored for the config key | +| key | String | The config key to set, prefixed with `board:{boardId}:` to apply setting only for a specific board | -###### Board configuration options +##### Request body -| Key | Value | -| --- | ----- | -| notify-due | `off`, `assigned` or `all` | -| calendar | Boolean | -| cardDetailsInModal | Boolean | -| cardIdBadge | Boolean | +| Parameter | Type | Description | +| --------- | ------- | --------------------------------------- | +| value | Any | The value that should be stored for the config key | ###### Example @@ -1514,6 +1509,15 @@ curl -X POST 'https://admin:admin@nextcloud.local/ocs/v2.php/apps/deck/api/v1.0/ --data-raw '{"value":false}' ``` +###### Board configuration options + +| Key | Value | +| --- | ----- | +| notify-due | `off`, `assigned` or `all` | +| calendar | Boolean | +| cardDetailsInModal | Boolean | +| cardIdBadge | Boolean | + ##### Response ```json From 64e127d29232444c86c62bd76a785d86644fe86c Mon Sep 17 00:00:00 2001 From: Viktor Diezel Date: Thu, 7 Aug 2025 09:01:25 +0200 Subject: [PATCH 21/30] docs: styling changes to headings Signed-off-by: Viktor Diezel --- docs/extra.css | 10 +++++++++- 1 file changed, 9 insertions(+), 1 deletion(-) diff --git a/docs/extra.css b/docs/extra.css index d927eb11ab..6b2a31edff 100644 --- a/docs/extra.css +++ b/docs/extra.css @@ -3,6 +3,14 @@ * SPDX-License-Identifier: AGPL-3.0-or-later */ + h5 { + font-size: 1rem; + } + + h6 { + font-size: 0.875rem; + } + .wy-menu li a { font-size: 1rem; } @@ -20,7 +28,7 @@ } .ep-heading { - margin-block-start: 3rem; + margin-block-start: 2.5rem; border-bottom: 2px solid grey; } From 92a849a226b0e175928a0b7ca5cf03e64bb4809f Mon Sep 17 00:00:00 2001 From: Viktor Diezel Date: Thu, 7 Aug 2025 09:02:34 +0200 Subject: [PATCH 22/30] docs: fixes path parameter description in restore board Signed-off-by: Viktor Diezel --- docs/API.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/API.md b/docs/API.md index b6fa469b5e..9af8dbf43b 100644 --- a/docs/API.md +++ b/docs/API.md @@ -424,7 +424,7 @@ Restore a deleted board by ID. | Parameter | Type | Description | | --------- | ------- | ---------------------------- | -| boardId | Integer | The id of the board to fetch | +| boardId | Integer | The id of the board to restore | ##### Response From 1845d8accde86d5a31fa364bad1cd32eeb872a7a Mon Sep 17 00:00:00 2001 From: Viktor Diezel Date: Thu, 7 Aug 2025 09:05:11 +0200 Subject: [PATCH 23/30] docs: adds missing example heading to update card Signed-off-by: Viktor Diezel --- docs/API.md | 2 ++ 1 file changed, 2 insertions(+) diff --git a/docs/API.md b/docs/API.md index 9af8dbf43b..0db999266c 100644 --- a/docs/API.md +++ b/docs/API.md @@ -844,6 +844,8 @@ Update a card by ID. | archived | bool | Whether the card is archived or not | | done | timestamp \| null | _(optional)_ The ISO-8601 formatted date when the card is marked as done (null indicates undone state) | +###### Example + ```json { "title": "Test card", From 4d22df252b955fc11d374b3b5c824c09aa01eaf9 Mon Sep 17 00:00:00 2001 From: Viktor Diezel Date: Thu, 7 Aug 2025 09:08:08 +0200 Subject: [PATCH 24/30] docs: fix Path heading for endpoints with different paths in v1.0 and v1.1 Signed-off-by: Viktor Diezel --- docs/API.md | 20 +++++--------------- 1 file changed, 5 insertions(+), 15 deletions(-) diff --git a/docs/API.md b/docs/API.md index 0db999266c..1d1b33246b 100644 --- a/docs/API.md +++ b/docs/API.md @@ -1179,7 +1179,7 @@ Returns the deleted label. #### List attachments {.ep-heading} -Get a list of all card attachments. When api-Version `v1.0` is used, then this endpoint returns only +Get a list of all card attachments. When api version `v1.0` is used, then this endpoint returns only attachments of type `deck_file`. ##### Path @@ -1226,14 +1226,12 @@ attachments of type `deck_file`. Get a card attachment by ID. -v1.0 ##### Path +v1.0 `GET /boards/{boardId}/stacks/{stackId}/cards/{cardId}/attachments/{attachmentId}`{.ep-path} v1.1 -##### Path - `GET /boards/{boardId}/stacks/{stackId}/cards/{cardId}/attachments/{type}/{attachmentId}`{.ep-path} ##### Path parameters @@ -1284,14 +1282,11 @@ Returns the card attachement. Update a card attachment by ID. -v1.0 ##### Path - +v1.0 `PUT /boards/{boardId}/stacks/{stackId}/cards/{cardId}/attachments/{attachmentId}`{.ep-path} v1.1 -##### Path - `PUT /boards/{boardId}/stacks/{stackId}/cards/{cardId}/attachments/{type}/{attachmentId}`{.ep-path} ##### Path parameters @@ -1321,14 +1316,12 @@ Returns the updated card attachment. Delete a card attachment by ID. -v1.0 ##### Path +v1.0 `DELETE /boards/{boardId}/stacks/{stackId}/cards/{cardId}/attachments/{attachmentId}`{.ep-path} v1.1 -##### Path - `DELETE /boards/{boardId}/stacks/{stackId}/cards/{cardId}/attachments/{type}/{attachmentId}`{.ep-path} ##### Path parameters @@ -1349,14 +1342,11 @@ Returns the deleted attachment. Restore a deleted card attachment by ID. -v1.0 ##### Path - +v1.0 `PUT /boards/{boardId}/stacks/{stackId}/cards/{cardId}/attachments/{attachmentId}/restore`{.ep-path} v1.1 -##### Path - `PUT /boards/{boardId}/stacks/{stackId}/cards/{cardId}/attachments/{type}/{attachmentId}/restore`{.ep-path} ##### Path parameters From 33e29c3262c0e9f8c5f082234a789a6b05c81d4d Mon Sep 17 00:00:00 2001 From: Viktor Diezel Date: Thu, 7 Aug 2025 09:38:43 +0200 Subject: [PATCH 25/30] docs: add docs for x-nc-deck-session Signed-off-by: Viktor Diezel --- docs/API.md | 12 ++++++++++-- 1 file changed, 10 insertions(+), 2 deletions(-) diff --git a/docs/API.md b/docs/API.md index 1d1b33246b..d0b60d005d 100644 --- a/docs/API.md +++ b/docs/API.md @@ -122,6 +122,14 @@ If available the ETag will also be part of JSON response objects as shown below } ``` +#### x-nc-deck-session + +The `x-nc-deck-session` header can be used when the [notify push client](https://github.com/nextcloud/notify_push) is active to receive live updates via websockets in clients. This is useful when multiple users are working on the same board at the same time. + +The header allows the server to detect who caused a certain update (e.g. create a card) and not notify the causing user about the change. This makes client logic easier, because the client has to do less work to understand which incoming live change was already applied locally. + +The value is the session token returned from the [create session endpoint](#create-session). + ## Changelog ### API version 1.0 @@ -438,7 +446,7 @@ Clone a board by ID. `POST /boards/{boardId}/clone`{.ep-path} -Creates a copy of the board. +Create a copy of the board. ##### Path parameters @@ -1787,7 +1795,7 @@ A list of comments will be provided under the `ocs.data` key. If no or no more c ### Sessions -#### Creates session {.ep-heading} +#### Create session {.ep-heading} Create a session. From 17725782a5b802945ca1ebcb4f84668b37c479fc Mon Sep 17 00:00:00 2001 From: Viktor Diezel Date: Thu, 7 Aug 2025 10:05:38 +0200 Subject: [PATCH 26/30] docs: adds docs for the overview/upcoming endpoint Signed-off-by: Viktor Diezel --- docs/API.md | 41 +++++++++++++++++++++++++++++++++++++++++ 1 file changed, 41 insertions(+) diff --git a/docs/API.md b/docs/API.md index d0b60d005d..887b1c893e 100644 --- a/docs/API.md +++ b/docs/API.md @@ -1912,3 +1912,44 @@ curl -X POST 'https://admin:admin@nextcloud/ocs/v2.php/apps/deck/api/v1.0/sessio } } ``` + +### Overview API + +#### List upcoming cards {.ep-heading} + +Get a list of cards across all user boards. The cards are grouped by their due dates: + +- overdue +- today +- tomorrow +- next 7 days +- later +- no due + +##### Path + +`GET /overview/upcoming`{.ep-path} + +##### Response + +The `ocs.data` key contains card groups that map to card arrays. A group without any cards will not be present in the result. Unlike the cards returned from the other API endpoints, upcoming cards embed a `board` object that contains the board's ID and title. + +```json +{ + "ocs": { + "meta": { + "status": "ok", + "statuscode": 200, + "message": "OK" + }, + "data": { + "overdue": [...], + "today": [...], + "tomorrow": [...], + "nextSevenDays": [...], + "later": [...], + "nodue": [...], + } + } +} +``` From 9f7a1067743d04ef21f4f5e74a1f3f178eb1f71d Mon Sep 17 00:00:00 2001 From: Viktor Diezel Date: Thu, 7 Aug 2025 10:19:34 +0200 Subject: [PATCH 27/30] docs: adds docs for the card/clone endpoint Signed-off-by: Viktor Diezel --- docs/API.md | 59 +++++++++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 59 insertions(+) diff --git a/docs/API.md b/docs/API.md index 887b1c893e..df5b5b0900 100644 --- a/docs/API.md +++ b/docs/API.md @@ -1953,3 +1953,62 @@ The `ocs.data` key contains card groups that map to card arrays. A group without } } ``` + +### Cards + +#### Clone card {.ep-heading} + +Clone a card. + +##### Path + +`POST /cards/${cardId}/clone`{.ep-path} + +##### Path parameters + +| Parameter | Type | Description | +| --------- | ------- | --------------------------------------- | +| cardId | Integer | The id of the card to be cloned | + +##### Request body + +| Parameter | Type | Description | +| --------- | ------- | ---------------------------------------------------- | +| targetStackId | Integer | _(optional)_ The id of the target stack, defaults to the current stack | + +##### Response + +The `ocs.data` key contains the cloned card. + +```json +{ + "ocs": { + "meta": { + "status": "ok", + "statuscode": 200, + "message": "OK" + }, + "data": { + "title":"Clone", + "description":null, + "stackId":6, + "type":"plain", + "lastModified":1541528026, + "createdAt":1541528026, + "labels":null, + "assignedUsers":null, + "attachments":null, + "attachmentCount":null, + "owner":"admin", + "order":999, + "archived":false, + "done":null, + "duedate": "2019-12-24T19:29:30+00:00", + "deletedAt":0, + "commentsUnread":0, + "id":10, + "overdue":0 + } + } +} +``` From c91a47bfd24c578ae23e6f149162fdc7507bee68 Mon Sep 17 00:00:00 2001 From: Viktor Diezel Date: Thu, 7 Aug 2025 10:45:12 +0200 Subject: [PATCH 28/30] docs: adds docs for search cards endpoint Signed-off-by: Viktor Diezel --- docs/API.md | 61 +++++++++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 61 insertions(+) diff --git a/docs/API.md b/docs/API.md index df5b5b0900..7bc2c7d7af 100644 --- a/docs/API.md +++ b/docs/API.md @@ -2012,3 +2012,64 @@ The `ocs.data` key contains the cloned card. } } ``` + +#### Search cards {.ep-heading} + +Search cards across all user boards that match the search term in title or description. Returned cards are sorted in decreasing order by `last_modified`. + +##### Path + +`GET /search?term=test`{.ep-path} + +##### Query string parameters + +| Parameter | Type | Description | +| --------- | ------- | --------------------------------------- | +| term | String | search term | +| limit | Integer | _(optional)_ maximum number of returned results | +| cursor | Integer | _(optional)_ UNIX timestamp in second. When set, only cards which were modified before `cursor` will be retrieved | + +##### Response + +The `ocs.data` key contains the matching cards. Unlike cards from the other API endpoint, these cards contain richer data of their stack and board under `relatedStack` and `relatedBoard` resp. + +```json +{ + "ocs": { + "meta": { + "status": "ok", + "statuscode": 200, + "message": "OK" + }, + "data": { + [ + "title":"Clone", + "description":null, + "stackId":6, + "type":"plain", + "lastModified":1541528026, + "createdAt":1541528026, + "labels":null, + "assignedUsers":null, + "attachments":null, + "attachmentCount":null, + "owner":"admin", + "order":999, + "archived":false, + "done":null, + "duedate": "2019-12-24T19:29:30+00:00", + "deletedAt":0, + "commentsUnread":0, + "id":10, + "overdue":0, + "relatedBoard": { + ... + }, + "relatedStack": { + ... + } + ] + } + } +} +``` From 732e2b4466028977f7e6d1e52250f3944a073ad2 Mon Sep 17 00:00:00 2001 From: Viktor Diezel Date: Thu, 7 Aug 2025 10:48:23 +0200 Subject: [PATCH 29/30] docs: add hint to OCS card API Signed-off-by: Viktor Diezel --- docs/API.md | 2 ++ 1 file changed, 2 insertions(+) diff --git a/docs/API.md b/docs/API.md index 7bc2c7d7af..34f83cddc8 100644 --- a/docs/API.md +++ b/docs/API.md @@ -730,6 +730,8 @@ Returns the deleted stack. The `deletedAt`-key contains the UNIX timestamp at de ### Cards +For searching cards across boards and cloning a card, see the [OCS Card API](#cards_1). + #### Get card {.ep-heading} Get a card by ID. From 710b06dc41bfb28942ccb0f9bf07be4cad3a5c6c Mon Sep 17 00:00:00 2001 From: Viktor Diezel Date: Thu, 7 Aug 2025 10:55:59 +0200 Subject: [PATCH 30/30] docs: link methods in Etag section Signed-off-by: Viktor Diezel --- docs/API.md | 16 ++++++++-------- 1 file changed, 8 insertions(+), 8 deletions(-) diff --git a/docs/API.md b/docs/API.md index 34f83cddc8..ccedceafff 100644 --- a/docs/API.md +++ b/docs/API.md @@ -101,14 +101,14 @@ curl -u admin:admin -X GET \ An ETag header is returned in order to determine if further child elements have been updated for the following endpoints: -- Fetch all user board `GET /api/v1.0/boards` -- Fetch a single board `GET /api/v1.0/boards/{boardId}` -- Fetch all stacks of a board `GET /api/v1.0/boards/{boardId}/stacks` -- Fetch a single stacks of a board `GET /api/v1.0/boards/{boardId}/stacks/{stackId}` -- Fetch a single card of a board `GET /api/v1.0/boards/{boardId}/stacks/{stackId}/cards/{cardId}` -- Fetch attachments of a card `GET /api/v1.0/boards/{boardId}/stacks/{stackId}/cards/{cardId}/attachments` - -If a `If-None-Match` header is provided and the requested element has not changed a `304` Not Modified response will be returned. +- [List user boards](#list-boards) +- [Get board by ID](#get-board) +- [List board stacks](#list-stacks) +- [Get stack by ID](#get-stack) +- [Get card by ID](#get-card) +- [List card attachments](#list-attachments) + +If a `If-None-Match` header is provided and the requested element has not changed a `304 Not Modified` response will be returned. Changes of child elements will propagate to their parents and also cause an update of the ETag which will be useful for determining if a sync is necessary on any client integration side. As an example, if a label is added to a card, the ETag of all related entities (the card, stack and board) will change.