ahtlon/deck
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases 1 Wiki Activity

Change level of api docs

Browse Source 
Signed-off-by: Julius Härtl <jus@bitgrid.net>
This commit is contained in:
Julius Härtl
2018-10-13 10:31:07 +02:00
parent fdd248b7d5
commit b494e9e1b0
2 changed files with 160 additions and 163 deletions
Download Patch File Download Diff File Expand all files Collapse all files

27
docs/API-Nextcloud.md Normal file
View File

@@ -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.

296
docs/API.md
View File

@@ -1,12 +1,11 @@
# Deck REST API
The REST API provides access for authenticated users to their data inside the Deck app. 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 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 - 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 - 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: 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 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 | | Parameter | Type | Description |
| --------- | ------ | ---------------------------------------------------- | | --------- | ------ | ---------------------------------------------------- |
@@ -84,9 +83,9 @@ Returns an array of board items
} }
``` ```
##### Response #### Response
###### 200 Success ##### 200 Success
```json ```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 | | Parameter | Type | Description |
| --------- | ------- | ---------------------------- | | --------- | ------- | ---------------------------- |
| boardId | Integer | The id of the board to fetch | | boardId | Integer | The id of the board to fetch |
##### Response #### Response
###### 200 Success ##### 200 Success
```json ```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 | | 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 | | Parameter | Type | Description |
| --------- | ------- | ---------------------------- | | --------- | ------- | ---------------------------- |
| boardId | Integer | The id of the board to fetch | | 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 | | Parameter | Type | Description |
| --------- | ------- | ---------------------------- | | --------- | ------- | ---------------------------- |
| boardId | Integer | The id of the board to fetch | | 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 | | Parameter | Type | Description |
| --------- | ------- | ---------------------------- | | --------- | ------- | ---------------------------- |
| boardId | Integer | The id of the board to fetch | | 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 | | Parameter | Type | Description |
| --------- | ------- | ---------------------------- | | --------- | ------- | ---------------------------- |
| boardId | Integer | The id of the board to fetch | | 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 | | Parameter | Type | Description |
| --------- | ------- | ---------------------------------------- | | --------- | ------- | ---------------------------------------- |
| boardId | Integer | The id of the board the stack belongs to | | boardId | Integer | The id of the board the stack belongs to |
| stackId | Integer | The if of the stack | | 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 | | Parameter | Type | Description |
| --------- | ------- | ---------------------------- | | --------- | ------- | ---------------------------- |
| boardId | Integer | The id of the board to fetch | | 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 | | Parameter | Type | Description |
| --------- | ------- | ---------------------------------------- | | --------- | ------- | ---------------------------------------- |
| boardId | Integer | The id of the board the stack belongs to | | boardId | Integer | The id of the board the stack belongs to |
| stackId | Integer | The if of the stack | | 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 | | Parameter | Type | Description |
| --------- | ------- | ---------------------------------------- | | --------- | ------- | ---------------------------------------- |
| boardId | Integer | The id of the board the stack belongs to | | boardId | Integer | The id of the board the stack belongs to |
| stackId | Integer | The if of the stack | | 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 | | Parameter | Type | Description |
| --------- | ------- | --------------------------------------- | | --------- | ------- | --------------------------------------- |
@@ -347,26 +346,26 @@ Returns an array of board items
| stackId | Integer | The if of the stack the card belongs to | | stackId | Integer | The if of the stack the card belongs to |
| cardId | Integer | The id of the card | | 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 | | Parameter | Type | Description |
| --------- | ------- | --------------------------------------- | | --------- | ------- | --------------------------------------- |
| boardId | Integer | The id of the board the card belongs to | | boardId | Integer | The id of the board the card belongs to |
| stackId | Integer | The if of the stack 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 | | Parameter | Type | Description |
| --------- | ------- | --------------------------------------- | | --------- | ------- | --------------------------------------- |
@@ -374,13 +373,13 @@ Returns an array of board items
| stackId | Integer | The if of the stack the card belongs to | | stackId | Integer | The if of the stack the card belongs to |
| cardId | Integer | The id of the card | | 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 | | Parameter | Type | Description |
| --------- | ------- | --------------------------------------- | | --------- | ------- | --------------------------------------- |
@@ -388,13 +387,13 @@ Returns an array of board items
| stackId | Integer | The if of the stack the card belongs to | | stackId | Integer | The if of the stack the card belongs to |
| cardId | Integer | The id of the card | | 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 | | Parameter | Type | Description |
| --------- | ------- | --------------------------------------- | | --------- | ------- | --------------------------------------- |
@@ -402,13 +401,13 @@ Returns an array of board items
| stackId | Integer | The if of the stack the card belongs to | | stackId | Integer | The if of the stack the card belongs to |
| cardId | Integer | The id of the card | | 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 | | Parameter | Type | Description |
| --------- | ------- | --------------------------------------- | | --------- | ------- | --------------------------------------- |
@@ -416,13 +415,13 @@ Returns an array of board items
| stackId | Integer | The if of the stack the card belongs to | | stackId | Integer | The if of the stack the card belongs to |
| cardId | Integer | The id of the card | | 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 | | Parameter | Type | Description |
| --------- | ------- | --------------------------------------- | | --------- | ------- | --------------------------------------- |
@@ -430,13 +429,13 @@ Returns an array of board items
| stackId | Integer | The if of the stack the card belongs to | | stackId | Integer | The if of the stack the card belongs to |
| cardId | Integer | The id of the card | | 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 | | Parameter | Type | Description |
| --------- | ------- | --------------------------------------- | | --------- | ------- | --------------------------------------- |
@@ -444,13 +443,13 @@ Returns an array of board items
| stackId | Integer | The if of the stack the card belongs to | | stackId | Integer | The if of the stack the card belongs to |
| cardId | Integer | The id of the card | | 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 | | Parameter | Type | Description |
| --------- | ------- | --------------------------------------- | | --------- | ------- | --------------------------------------- |
@@ -458,68 +457,68 @@ Returns an array of board items
| stackId | Integer | The if of the stack the card belongs to | | stackId | Integer | The if of the stack the card belongs to |
| cardId | Integer | The id of the card | | 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 | | Parameter | Type | Description |
| --------- | ------- | ---------------------------------------- | | --------- | ------- | ---------------------------------------- |
| boardId | Integer | The id of the board the label belongs to | | boardId | Integer | The id of the board the label belongs to |
| labelId | Integer | The id of the label | | 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 | | Parameter | Type | Description |
| --------- | ------- | ---------------------------------------- | | --------- | ------- | ---------------------------------------- |
| boardId | Integer | The id of the board the label belongs to | | 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 | | Parameter | Type | Description |
| --------- | ------- | ---------------------------------------- | | --------- | ------- | ---------------------------------------- |
| boardId | Integer | The id of the board the label belongs to | | boardId | Integer | The id of the board the label belongs to |
| labelId | Integer | The id of the label | | 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 | | Parameter | Type | Description |
| --------- | ------- | ---------------------------------------- | | --------- | ------- | ---------------------------------------- |
| boardId | Integer | The id of the board the label belongs to | | boardId | Integer | The id of the board the label belongs to |
| labelId | Integer | The id of the label | | 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 | | Parameter | Type | Description |
| --------- | ------- | --------------------------------------- | | --------- | ------- | --------------------------------------- |
@@ -527,13 +526,13 @@ Returns an array of board items
| stackId | Integer | The if of the stack the card belongs to | | stackId | Integer | The if of the stack the card belongs to |
| cardId | Integer | The id of the card | | 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 | | Parameter | Type | Description |
| ------------ | ------- | --------------------------------------------- | | ------------ | ------- | --------------------------------------------- |
@@ -542,13 +541,13 @@ Returns an array of board items
| cardId | Integer | The id of the card the attachment belongs to | | cardId | Integer | The id of the card the attachment belongs to |
| attachmentId | Integer | The id of the attachment | | 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 | | Parameter | Type | Description |
| --------- | ------- | --------------------------------------------- | | --------- | ------- | --------------------------------------------- |
@@ -556,13 +555,13 @@ Returns an array of board items
| stackId | Integer | The if of the stack the attachment belongs to | | stackId | Integer | The if of the stack the attachment belongs to |
| cardId | Integer | The id of the card 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 | | Parameter | Type | Description |
| ------------ | ------- | --------------------------------------------- | | ------------ | ------- | --------------------------------------------- |
@@ -571,13 +570,13 @@ Returns an array of board items
| cardId | Integer | The id of the card the attachment belongs to | | cardId | Integer | The id of the card the attachment belongs to |
| attachmentId | Integer | The id of the attachment | | 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 | | Parameter | Type | Description |
| ------------ | ------- | --------------------------------------------- | | ------------ | ------- | --------------------------------------------- |
@@ -586,13 +585,13 @@ Returns an array of board items
| cardId | Integer | The id of the card the attachment belongs to | | cardId | Integer | The id of the card the attachment belongs to |
| attachmentId | Integer | The id of the attachment | | 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 | | Parameter | Type | Description |
| ------------ | ------- | --------------------------------------------- | | ------------ | ------- | --------------------------------------------- |
@@ -601,36 +600,7 @@ Returns an array of board items
| cardId | Integer | The id of the card the attachment belongs to | | cardId | Integer | The id of the card the attachment belongs to |
| attachmentId | Integer | The id of the attachment | | 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.