From b494e9e1b032711955e88f83766695869d889aa1 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Julius=20H=C3=A4rtl?= Date: Sat, 13 Oct 2018 10:31:07 +0200 Subject: [PATCH] Change level of api docs MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Signed-off-by: Julius Härtl --- docs/API-Nextcloud.md | 27 ++++ docs/API.md | 296 +++++++++++++++++++----------------------- 2 files changed, 160 insertions(+), 163 deletions(-) create mode 100644 docs/API-Nextcloud.md diff --git a/docs/API-Nextcloud.md b/docs/API-Nextcloud.md new file mode 100644 index 000000000..8c657d78a --- /dev/null +++ b/docs/API-Nextcloud.md @@ -0,0 +1,27 @@ +# Nextcloud APIs + +## Comments + +Comments are stored using the Nextcloud Comments API. You can use the WebDAV endpoint of Nextcloud to fetch, update and delete comments. + +### List comments + +PROPFIND`remote.php/dav/comments/deckCard/{cardId}` + +### Create comment + +POST `remote.php/dav/comments/deckCard/{cardId}` + +### Update comment + +PROPPATCH `remote.php/dav/comments/deckCard/{cardId}/{commentId}` + +### Delete comment + +DELETE `remote.php/dav/comments/deckCard/{cardId}/{commentId}` + +## Activity + +The Nextcloud activity app provides an API to fetch activities filtered for deck: [Activity app API documentation](https://github.com/nextcloud/activity/blob/master/docs/endpoint-v2.md) + +The deck app offers a filter `deck` to only request activity events that are relevant. diff --git a/docs/API.md b/docs/API.md index 16043a594..4078ea385 100644 --- a/docs/API.md +++ b/docs/API.md @@ -1,12 +1,11 @@ -# Deck REST API The REST API provides access for authenticated users to their data inside the Deck app. -## Prequisited +# Prequisited 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 -### Naming +## Naming - Board is the the project like grouping of tasks that can be shared to different users and groups @@ -16,9 +15,9 @@ All requests require a `OCS-APIRequest` HTTP header to be set to `true` and a `C - Labels are defined on a board level and can be assigned to any number of cards -### Global responses +## Global responses -#### 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: @@ -29,15 +28,15 @@ In any case a user doesn't have access to a requested entity, a 403 error will b } ``` -## Endpoints +# Endpoints -### Boards +## Boards -#### GET /boards - Get a list of boards +### GET /boards - Get a list of boards -##### Response +#### Response -###### 200 Success +##### 200 Success Returns an array of board items @@ -68,9 +67,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 | | --------- | ------ | ---------------------------------------------------- | @@ -84,9 +83,9 @@ Returns an array of board items } ``` -##### Response +#### Response -###### 200 Success +##### 200 Success ```json { @@ -141,17 +140,17 @@ Returns an array of board items } ``` -#### 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 { @@ -212,9 +211,9 @@ Returns an array of board items } ``` -#### PUT /boards/{boardId} - Update board details +### PUT /boards/{boardId} - Update board details -##### Request body +#### Request body | Parameter | Type | Description | | --------- | ------ | ---------------------------------------------------- | @@ -230,116 +229,116 @@ Returns an array of board items } ``` -##### 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 -### Stacks +## Stacks -#### GET /board/{boardId}/stacks - Get stacks +### GET /board/{boardId}/stacks - Get stacks -##### Request parameters +#### Request parameters | Parameter | Type | Description | | --------- | ------- | ---------------------------- | | boardId | Integer | The id of the board to fetch | -##### Response +#### Response -###### 200 Success +##### 200 Success -#### GET /board/{boardId}/stacks/archived - Get list of archived stacks +### GET /board/{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 -###### 200 Success +##### 200 Success -#### GET /board/{boardId}/stacks/{stackId} - Get stack details +### GET /board/{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 if of the stack | -##### Response +#### Response -###### 200 Success +##### 200 Success -#### POST /board/{boardId}/stacks - Create a new stack +### POST /board/{boardId}/stacks - Create a new stack -##### Request parameters +#### Request parameters | Parameter | Type | Description | | --------- | ------- | ---------------------------- | | boardId | Integer | The id of the board to fetch | -##### Response +#### Response -###### 200 Success +##### 200 Success -#### PUT /board/{boardId}/stacks/{stackId} - Update stack details +### PUT /board/{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 if of the stack | -##### Response +#### Response -###### 200 Success +##### 200 Success -#### DELETE /board/{boardId}/stacks/{stackId} - Delete a stack +### DELETE /board/{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 if of the stack | -##### Response +#### Response -###### 200 Success +##### 200 Success -### Cards +## Cards -#### GET /board/{boardId}/stacks/{stackId}/cards/{cardId} - Get card details +### GET /board/{boardId}/stacks/{stackId}/cards/{cardId} - Get card details -##### Request parameters +#### Request parameters | Parameter | Type | Description | | --------- | ------- | --------------------------------------- | @@ -347,26 +346,26 @@ Returns an array of board items | stackId | Integer | The if of the stack the card belongs to | | cardId | Integer | The id of the card | -##### Response +#### Response -###### 200 Success +##### 200 Success -#### POST /board/{boardId}/stacks/{stackId}/cards - Create a new card +### POST /board/{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 if of the stack the card belongs to | -##### Response +#### Response -###### 200 Success +##### 200 Success -#### PUT /board/{boardId}/stacks/{stackId}/cards/{cardId} - Update card details +### PUT /board/{boardId}/stacks/{stackId}/cards/{cardId} - Update card details -##### Request parameters +#### Request parameters | Parameter | Type | Description | | --------- | ------- | --------------------------------------- | @@ -374,13 +373,13 @@ Returns an array of board items | stackId | Integer | The if of the stack the card belongs to | | cardId | Integer | The id of the card | -##### Response +#### Response -###### 200 Success +##### 200 Success -#### DELETE /board/{boardId}/stacks/{stackId}/cards/{cardId} - Delete a card +### DELETE /board/{boardId}/stacks/{stackId}/cards/{cardId} - Delete a card -##### Request parameters +#### Request parameters | Parameter | Type | Description | | --------- | ------- | --------------------------------------- | @@ -388,13 +387,13 @@ Returns an array of board items | stackId | Integer | The if of the stack the card belongs to | | cardId | Integer | The id of the card | -##### Response +#### Response -###### 200 Success +##### 200 Success -#### PUT /board/{boardId}/stacks/{stackId}/cards/{cardId}/assignLabel - Assign a label to a card +### PUT /board/{boardId}/stacks/{stackId}/cards/{cardId}/assignLabel - Assign a label to a card -##### Request parameters +#### Request parameters | Parameter | Type | Description | | --------- | ------- | --------------------------------------- | @@ -402,13 +401,13 @@ Returns an array of board items | stackId | Integer | The if of the stack the card belongs to | | cardId | Integer | The id of the card | -##### Response +#### Response -###### 200 Success +##### 200 Success -#### PUT /board/{boardId}/stacks/{stackId}/cards/{cardId}/removeLabel - Remove a label to a card +### PUT /board/{boardId}/stacks/{stackId}/cards/{cardId}/removeLabel - Remove a label to a card -##### Request parameters +#### Request parameters | Parameter | Type | Description | | --------- | ------- | --------------------------------------- | @@ -416,13 +415,13 @@ Returns an array of board items | stackId | Integer | The if of the stack the card belongs to | | cardId | Integer | The id of the card | -##### Response +#### Response -###### 200 Success +##### 200 Success -#### PUT /board/{boardId}/stacks/{stackId}/cards/{cardId}/assignUser - Assign a user to a card +### PUT /board/{boardId}/stacks/{stackId}/cards/{cardId}/assignUser - Assign a user to a card -##### Request parameters +#### Request parameters | Parameter | Type | Description | | --------- | ------- | --------------------------------------- | @@ -430,13 +429,13 @@ Returns an array of board items | stackId | Integer | The if of the stack the card belongs to | | cardId | Integer | The id of the card | -##### Response +#### Response -###### 200 Success +##### 200 Success -#### PUT /board/{boardId}/stacks/{stackId}/cards/{cardId}/unassignUser - Assign a user to a card +### PUT /board/{boardId}/stacks/{stackId}/cards/{cardId}/unassignUser - Assign a user to a card -##### Request parameters +#### Request parameters | Parameter | Type | Description | | --------- | ------- | --------------------------------------- | @@ -444,13 +443,13 @@ Returns an array of board items | stackId | Integer | The if of the stack the card belongs to | | cardId | Integer | The id of the card | -##### Response +#### Response -###### 200 Success +##### 200 Success -#### PUT /board/{boardId}/stacks/{stackId}/cards/{cardId}/reorder - Change the sorting order of a card +### PUT /board/{boardId}/stacks/{stackId}/cards/{cardId}/reorder - Change the sorting order of a card -##### Request parameters +#### Request parameters | Parameter | Type | Description | | --------- | ------- | --------------------------------------- | @@ -458,68 +457,68 @@ Returns an array of board items | stackId | Integer | The if of the stack the card belongs to | | cardId | Integer | The id of the card | -##### Response +#### Response -###### 200 Success +##### 200 Success -### Labels +## Labels -#### GET /board/{boardId}/labels/{labelId} - Get label details +### GET /board/{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 -#### POST /board/{boardId}/labels - Create a new label +### POST /board/{boardId}/labels - Create a new label -##### Request parameters +#### Request parameters | Parameter | Type | Description | | --------- | ------- | ---------------------------------------- | | boardId | Integer | The id of the board the label belongs to | -##### Response +#### Response -###### 200 Success +##### 200 Success -#### PUT /board/{boardId}/labels/{labelId} - Update label details +### PUT /board/{boardId}/labels/{labelId} - Update 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 -#### DELETE /board/{boardId}/labels/{labelId} - Delete a label +### DELETE /board/{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 /board/{boardId}/stacks/{stackId}/cards/{cardId}/attachments - Get a list of attachments +### GET /board/{boardId}/stacks/{stackId}/cards/{cardId}/attachments - Get a list of attachments -##### Request parameters +#### Request parameters | Parameter | Type | Description | | --------- | ------- | --------------------------------------- | @@ -527,13 +526,13 @@ Returns an array of board items | stackId | Integer | The if of the stack the card belongs to | | cardId | Integer | The id of the card | -##### Response +#### Response -###### 200 Success +##### 200 Success -#### GET /board/{boardId}/stacks/{stackId}/cards/{cardId}/attachments/{attachmentId} - Get the attachment file +### GET /board/{boardId}/stacks/{stackId}/cards/{cardId}/attachments/{attachmentId} - Get the attachment file -##### Request parameters +#### Request parameters | Parameter | Type | Description | | ------------ | ------- | --------------------------------------------- | @@ -542,13 +541,13 @@ Returns an array of board items | 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 /board/{boardId}/stacks/{stackId}/cards/{cardId}/attachments - Upload an attachment +### POST /board/{boardId}/stacks/{stackId}/cards/{cardId}/attachments - Upload an attachment -##### Request parameters +#### Request parameters | Parameter | Type | Description | | --------- | ------- | --------------------------------------------- | @@ -556,13 +555,13 @@ Returns an array of board items | stackId | Integer | The if of the stack the attachment belongs to | | cardId | Integer | The id of the card the attachment belongs to | -##### Response +#### Response -###### 200 Success +##### 200 Success -#### PUT /board/{boardId}/stacks/{stackId}/cards/{cardId}/attachments/{attachmentId} - Update an attachment +### PUT /board/{boardId}/stacks/{stackId}/cards/{cardId}/attachments/{attachmentId} - Update an attachment -##### Request parameters +#### Request parameters | Parameter | Type | Description | | ------------ | ------- | --------------------------------------------- | @@ -571,13 +570,13 @@ Returns an array of board items | cardId | Integer | The id of the card the attachment belongs to | | attachmentId | Integer | The id of the attachment | -##### Response +#### Response -###### 200 Success +##### 200 Success -#### DELETE /board/{boardId}/stacks/{stackId}/cards/{cardId}/attachments/{attachmentId} - Delete an attachment +### DELETE /board/{boardId}/stacks/{stackId}/cards/{cardId}/attachments/{attachmentId} - Delete an attachment -##### Request parameters +#### Request parameters | Parameter | Type | Description | | ------------ | ------- | --------------------------------------------- | @@ -586,13 +585,13 @@ Returns an array of board items | 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 /board/{boardId}/stacks/{stackId}/cards/{cardId}/attachments/{attachmentId}/restore - Resore a deleted attachment +### PUT /board/{boardId}/stacks/{stackId}/cards/{cardId}/attachments/{attachmentId}/restore - Resore a deleted attachment -##### Request parameters +#### Request parameters | Parameter | Type | Description | | ------------ | ------- | --------------------------------------------- | @@ -601,36 +600,7 @@ Returns an array of board items | cardId | Integer | The id of the card the attachment belongs to | | attachmentId | Integer | The id of the attachment | -##### Response +#### Response -###### 200 Success +##### 200 Success -## Other APIs - -### Comments - -Comments are stored using the Nextcloud Comments API. You can use the WebDAV endpoint of Nextcloud to fetch, update and delete comments. - -#### List comments - -PROPFIND`remote.php/dav/comments/deckCard/{cardId}` - -#### Create comment - -POST `remote.php/dav/comments/deckCard/{cardId}` - -#### Update comment - -PROPPATCH `remote.php/dav/comments/deckCard/{cardId}/{commentId}` - -#### Delete comment - -DELETE `remote.php/dav/comments/deckCard/{cardId}/{commentId}` - -### Activity - -The Nextcloud activity app provides an API to fetch activities filtered for deck: - -https://github.com/nextcloud/activity/blob/master/docs/endpoint-v2.md - -The deck app offers a filter `deck` to only request activity events that are relevant.