Add API docs for comments OCS API
Signed-off-by: Julius Härtl <jus@bitgrid.net>
This commit is contained in:
Julius Härtl
229
docs/API.md
229
docs/API.md
@@ -936,3 +936,232 @@ For now only `deck_file` is supported as an attachment type.
|
||||
|
||||
##### 200 Success
|
||||
|
||||
# OCS API
|
||||
|
||||
The following endpoints are available tough 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.
|
||||
|
||||
## Comments
|
||||
|
||||
### GET /cards/{cardId}/comments - List comments
|
||||
|
||||
#### Request parameters
|
||||
|
||||
string $cardId, int $limit = 20, int $offset = 0
|
||||
|
||||
| Parameter | Type | Description |
|
||||
| --------- | ------- | --------------------------------------- |
|
||||
| cardId | Integer | The id of the 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 |
|
||||
|
||||
```
|
||||
curl 'https://admin:admin@nextcloud/ocs/v2.php/apps/deck/api/v1.0/cards/12/comments' \
|
||||
-H 'Accept: application/json' -H 'OCS-APIRequest: true'
|
||||
```
|
||||
|
||||
#### 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
|
||||
|
||||
```
|
||||
{
|
||||
"ocs": {
|
||||
"meta": {
|
||||
"status": "ok",
|
||||
"statuscode": 200,
|
||||
"message": "OK"
|
||||
},
|
||||
"data": [
|
||||
{
|
||||
"id": "175",
|
||||
"objectId": "12",
|
||||
"message": "This is a comment with a mention to @alice",
|
||||
"actorId": "admin",
|
||||
"actorType": "users",
|
||||
"actorDisplayName": "Administrator",
|
||||
"creationDateTime": "2020-03-10T10:23:07+00:00",
|
||||
"mentions": [
|
||||
{
|
||||
"mentionId": "alice",
|
||||
"mentionType": "user",
|
||||
"mentionDisplayName": "alice"
|
||||
}
|
||||
]
|
||||
}
|
||||
]
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
|
||||
### POST /cards/{cardId}/comments - Create a new comment
|
||||
|
||||
#### Request parameters
|
||||
|
||||
| Parameter | Type | Description |
|
||||
| --------- | ------- | --------------------------------------- |
|
||||
| cardId | Integer | The id of the card |
|
||||
| message | String | The message of the comment, maximum length is limited to 1000 characters |
|
||||
| parentId | Integer | The start offset used for pagination, 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.
|
||||
|
||||
```
|
||||
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'
|
||||
--data '{"message":"My message to @bob","parentId":null}'
|
||||
```
|
||||
|
||||
#### 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
|
||||
|
||||
```
|
||||
{
|
||||
"ocs": {
|
||||
"meta": {
|
||||
"status": "ok",
|
||||
"statuscode": 200,
|
||||
"message": "OK"
|
||||
},
|
||||
"data": {
|
||||
"id": "177",
|
||||
"objectId": "13",
|
||||
"message": "My message to @bob",
|
||||
"actorId": "admin",
|
||||
"actorType": "users",
|
||||
"actorDisplayName": "Administrator",
|
||||
"creationDateTime": "2020-03-10T10:30:17+00:00",
|
||||
"mentions": [
|
||||
{
|
||||
"mentionId": "bob",
|
||||
"mentionType": "user",
|
||||
"mentionDisplayName": "bob"
|
||||
}
|
||||
]
|
||||
}
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
##### 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
|
||||
|
||||
|
||||
### PUT /cards/{cardId}/comments/{commentId} - Update a new comment
|
||||
|
||||
#### Request parameters
|
||||
|
||||
| Parameter | Type | Description |
|
||||
| --------- | ------- | --------------------------------------- |
|
||||
| cardId | Integer | The id of the card |
|
||||
| commentId | Integer | The id of the comment |
|
||||
| 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.
|
||||
|
||||
```
|
||||
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'
|
||||
--data '{"message":"My message"}'
|
||||
```
|
||||
|
||||
#### 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
|
||||
|
||||
```
|
||||
{
|
||||
"ocs": {
|
||||
"meta": {
|
||||
"status": "ok",
|
||||
"statuscode": 200,
|
||||
"message": "OK"
|
||||
},
|
||||
"data": {
|
||||
"id": "177",
|
||||
"objectId": "13",
|
||||
"message": "My message",
|
||||
"actorId": "admin",
|
||||
"actorType": "users",
|
||||
"actorDisplayName": "Administrator",
|
||||
"creationDateTime": "2020-03-10T10:30:17+00:00",
|
||||
"mentions": []
|
||||
}
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
##### 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 /cards/{cardId}/comments/{commentId} - Delete a comment
|
||||
|
||||
#### Request parameters
|
||||
|
||||
| Parameter | Type | Description |
|
||||
| --------- | ------- | --------------------------------------- |
|
||||
| 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.
|
||||
|
||||
```
|
||||
curl -X DELETE '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'
|
||||
```
|
||||
|
||||
#### 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
|
||||
|
||||
```
|
||||
{
|
||||
"ocs": {
|
||||
"meta": {
|
||||
"status": "ok",
|
||||
"statuscode": 200,
|
||||
"message": "OK"
|
||||
},
|
||||
"data": []
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
##### 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
|
||||
|
||||
Reference in New Issue
Block a user