diff options
author | dartcafe <github@dartcafe.de> | 2020-06-20 16:25:17 +0300 |
---|---|---|
committer | dartcafe <github@dartcafe.de> | 2020-06-20 16:25:17 +0300 |
commit | af77c5cba4642761c644cae761fbedcc82acc4e6 (patch) | |
tree | c8ce8840b16378eca82cf10faf826a02549369bb /docs | |
parent | feb0fc3e16bde4d0fb0871e50a6c60eca83483d2 (diff) |
API documentation
Diffstat (limited to 'docs')
-rw-r--r-- | docs/API_v1.0.md | 112 |
1 files changed, 110 insertions, 2 deletions
diff --git a/docs/API_v1.0.md b/docs/API_v1.0.md index a8125dc8..af4efc16 100644 --- a/docs/API_v1.0.md +++ b/docs/API_v1.0.md @@ -1,8 +1,13 @@ +# DRAFT + +This documentation and the API are not final and may contain issues and bugs! +Details may change! + To act like a authenticated user, use username:password@ prefix in the URL Parameters in the body override the URL-parameter -Base URL for all calls: /index.php/apps/polls/api/1.0/ +Base URL for all calls: /index.php/apps/polls Example calls: * Gets all comments of poll no. 1 `https://username:password@nextcloud.local/index.php/apps/polls/api/1.0/poll/1/comments` @@ -22,20 +27,95 @@ Example calls: | DELETE | /api/v1.0/poll/permanent{pollId} | Delete poll permanently | 200, 403, 404 | | GET | /api/v1.0/poll/enum | Get valid enums | 200, 403, 404 | +## Add poll + +```json +{ + "type": "datePoll", + "title": "Test" +} +``` + +## Update poll +```json +{ + "poll": { + "title": "Changed Title", + "description": "Updated description", + "expire": 0, + "deleted": 0, + "access": "hidden", + "anonymous": 1, + "allowMaybe": 1, + "showResults": "never", + "adminAccess": 1 + } +} +``` + +### Keys and values +| Key | Type | description | +| ------- | ------- | -------------------| +| expire | integer | unix timestamp | +| deleted | integer | unix timestamp | + + + # Options | Method | Endpoint | Description | Return codes | | --------- | ----------------------------------- | ---------------------------- | ------------------ | -| GET | /api/v1.0/poll/{pollId}/options | Get options | 200, 403, 404 | +| GET | /api/v1.0/poll/{pollId}/options | Get options as array | 200, 403, 404 | | POST | /api/v1.0/option | Add new option with Payload | 201, 403, 404, 409 | | PUT | /api/v1.0/option | Update option with Payload | 200, 403, 404 | | DELETE | /api/v1.0/option/{optionId} | Delete option | 200, 403, 404 | +## add option +```json +{ + "pollId": 139, + "pollOptionText": "19-06-2020 17:00:00", + "timestamp": 0, +} +``` + +## Update option +```json +{ + "id": 17, + "pollId": 1, + "pollOptionText": "poll option", + "timestamp": 0, + "order": 1, + "confirmed": 1590762104 +}, +``` + +### Keys and values +| Key | Type | description | +| -------------- | ------- | ------------------------------------- | +| id | String | id overrides optionID if used | +| pollOptionText | String | poll text or date option in UTC | +| confirmed | Integer | unix timestamp | +| timestamp | Integer | unix timestamp for date option | +| order | Integer | position on option order for textpolls | + +* if timestamp is given in a date poll, the poll option text is ignored + # Votes | Method | Endpoint | Description | Return codes | | --------- | ----------------------------------- | ---------------------------- | ------------------ | | GET | /api/v1.0/poll/{pollId}/votes | Get votes | 200, 403, 404 | | POST | /api/v1.0/vote | Set vote with Payload | 200, 403, 404 | +## set vote +```json +{ + "pollId": 1, + "pollOptionText": "Saturn", + "setTo" :"yes" +} +``` + # Comments | Method | Endpoint | Description | Return codes | | --------- | ----------------------------------- | ---------------------------- | ------------------ | @@ -43,6 +123,14 @@ Example calls: | POST | /api/v1.0/comment | Add new commen twith Payload | 201, 403, 404 | | DELETE | /api/v1.0/comment/{commentId} | Delete comment | 200, 403, 404 | +# Add comment +```json +{ + "pollId": 1, + "message": "Comment text" +} +``` + # Shares | Method | Endpoint | Description | Return codes | | --------- | ----------------------------------- | ---------------------------- | ------------------ | @@ -51,6 +139,26 @@ Example calls: | POST | /api/v1.0/share | Add new share with Payload | 201, 403, 404 | | DELETE | /api/v1.0/share/{token} | Delete share | 200, 404, 409 | +# Add share + +## public share +```json +{ + "type": "public", + "pollId": 1 +} +``` +## user share +tbd + +## email share +tbd + +## contact share +tbd + + + # Subscription | Method | Endpoint | Description | Return codes | | --------- | ----------------------------------- | ---------------------------- | ------------------ | |