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

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