From feb0fc3e16bde4d0fb0871e50a6c60eca83483d2 Mon Sep 17 00:00:00 2001 From: dartcafe Date: Sat, 20 Jun 2020 13:15:48 +0200 Subject: Updated API and code polish, tidy --- docs/API_v1.0.md | 206 ++++++++++++------------------------------------------- 1 file changed, 42 insertions(+), 164 deletions(-) (limited to 'docs') diff --git a/docs/API_v1.0.md b/docs/API_v1.0.md index c56653a0..a8125dc8 100644 --- a/docs/API_v1.0.md +++ b/docs/API_v1.0.md @@ -10,172 +10,50 @@ Example calls: `curl -u username:password -X GET https://nextcloud.local/index.php/apps/polls/api/1.0/poll/1/comments` ``` -# Comments -## List all comments by poll -GET `/index.php/apps/polls/api/1.0/poll/{pollId}/comments` - -### Return HTTP status 200 -Response body contains all comments of the poll with {pollId} - -### Return HTTP status 403 - Forbidden -Authorization is missing use correct username:passwort - -### Return HTTP status 404 - Not found -commentId not found - -## Post a new comment -POST `/index.php/apps/polls/api/1.0/comment` - -Data -```json -{ - "message": "Comment text", - "pollId": 1, -} -``` -### Return HTTP status 201 - Created -Comment successfully created -Response Body contains the comment as json - -### Return HTTP status 403 - Forbidden -Authorization is missing use correct username:passwort - -### Return HTTP status 404 - Not found -pollId not found - -## Delete a comment -DELETE `/index.php/apps/polls/api/1.0/comment/{commentId}` - -### Return HTTP status 200 -Response body contains the commentId - -### Return HTTP status 403 - Forbidden -Authorization is missing, use correct username:passwort - -### Return HTTP status 404 - Not found -commentId not found +# Poll +| Method | Endpoint | Description | Return codes | +| --------- | ----------------------------------- | ---------------------------- | ------------------ | +| GET | /api/v1.0/polls | Get polls list as array | 200, 403, 404 | +| GET | /api/v1.0/poll/{pollId} | Get poll with {pollId} | 200, 403, 404 | +| POST | /api/v1.0/poll/add | Add new poll with payload | 201, 403, 404 | +| POST | /api/v1.0/poll/clone/{pollId} | Clone poll {pollId} | 201, 403, 404 | +| PUT | /api/v1.0/poll/{pollId} | Update poll | 200, 403, 404, 409 | +| DELETE | /api/v1.0/poll/{pollId} | Delete poll logical | 200, 403, 404 | +| 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 | # Options -## List all options by poll -GET `/index.php/apps/polls/api/1.0/poll/{pollId}/options` - -### Return HTTP status 200 -Response body contains all options of the poll with {pollId} - -### Return HTTP status 403 - Forbidden -Authorization is missing, use correct username:passwort - -### Return HTTP status 404 - Not found -pollId not found - -## Post a new option -POST `/index.php/apps/polls/api/1.0/option` - -Data -```json -{ - "message": "Comment text", - "pollId": 1, -} -``` -### Return HTTP status 201 - Created -Comment successfully created -Response Body contains the option as json - -### Return HTTP status 403 - Forbidden -Authorization is missing use correct username:passwort - -### Return HTTP status 404 - Not found -pollId not found - -### Return HTTP status 409 - Conflict -The option already exists in this poll - -## Delete an option -DELETE `/index.php/apps/polls/api/1.0/option/{optionId}` - -### Return HTTP status 200 - OK -Response body contains the optionId +| Method | Endpoint | Description | Return codes | +| --------- | ----------------------------------- | ---------------------------- | ------------------ | +| GET | /api/v1.0/poll/{pollId}/options | Get options | 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 | + +# 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 | -### Return HTTP status 403 - Forbidden -Authorization is missing use correct username:passwort - -### Return HTTP status 404 - Not found -optionId not found +# Comments +| Method | Endpoint | Description | Return codes | +| --------- | ----------------------------------- | ---------------------------- | ------------------ | +| GET | /api/v1.0/poll/{pollId}/comments | Get comments | 200, 403, 404 | +| POST | /api/v1.0/comment | Add new commen twith Payload | 201, 403, 404 | +| DELETE | /api/v1.0/comment/{commentId} | Delete comment | 200, 403, 404 | # Shares -## List all shares by poll -GET `/index.php/apps/polls/api/1.0/poll/{pollId}/shares` - -### Return HTTP status 200 -Response body contains all shares of the poll with {pollId} - -### Return HTTP status 403 - Forbidden -Authorization is missing, use correct username:passwort - -### Return HTTP status 404 - Not found -pollId not found - -## Add a share -POST `/index.php/apps/polls/api/1.0/share` - -Data -```json -{ - "type": "public", - "pollId": 1 -} -``` - -```json -{ - "type": "group", - "pollId": 1, - "userId": "groupId" -} -``` - -```json -{ - "type": "user", - "pollId": 1, - "userId": "userId" -} -``` - -```json -{ - "type": "email", - "pollId": 1, - "userEmail": "user@foo.com" -} -``` - -```json -{ - "type": "contact", - "pollId": 1, - "userId": "Contacts'name", - "userEmail": "user@foo.com" -} -``` - - -### Return HTTP status 201 - Created -Comment successfully created -Response Body contains the option as json - -### Return HTTP status 403 - Forbidden -Authorization is missing use correct username:passwort - -## Delete a share -DELETE `/index.php/apps/polls/api/1.0/share/{token}` - -### Return HTTP status 200 - OK -Response body contains the deleted share - -### Return HTTP status 403 - Forbidden -Authorization is missing use correct username:passwort - -### Return HTTP status 404 - Not found -share not found +| Method | Endpoint | Description | Return codes | +| --------- | ----------------------------------- | ---------------------------- | ------------------ | +| GET | /api/v1.0/poll/{pollId}/shares | Get shares | 200, 403, 404 | +| GET | /api/v1.0/share/{token} | Get share by token | 200, 403, 404 | +| POST | /api/v1.0/share | Add new share with Payload | 201, 403, 404 | +| DELETE | /api/v1.0/share/{token} | Delete share | 200, 404, 409 | + +# Subscription +| Method | Endpoint | Description | Return codes | +| --------- | ----------------------------------- | ---------------------------- | ------------------ | +| GET | /api/v1.0/poll/{pollId}/subscription | Get subscription status | 200, 403, 404 | +| PUT | /api/v1.0/poll/{pollId}/subscription | Subcribe | 201, 403 | +| DELETE | /api/v1.0/poll/{pollId}/subscription | unsubscribe | 200, 403 | -- cgit v1.2.3