API

DRAFT

This documentation and the API are not final, out of date and may contain issues and bugs! Details may change!

Find the actual endpoints by looking into the ApiControllers.

• 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: /ocs/v2.php/apps/polls/api/v1.0

Example calls:

• Gets all comments of poll no. 1 https://username:password@nextcloud.local/ocs/v2.php/apps/polls/api/v1.0/poll/1/comments

`curl -u username:password -X GET https://nextcloud.local/ocs/v2.php/apps/polls/api/v1.0/poll/1/comments`

Poll

Default functions

Method	Endpoint	Payload	Description	Return codes	Return value
GET	/polls	no	Get array of polls	200, 403, 404	array
GET	/poll/{pollId}	no	Get poll with {pollId}	200, 403, 404	requested poll
POST	/poll	yes	Add new poll	201, 403, 404	added poll
PUT	/poll/{pollId}	yes	Update poll	200, 403, 404, 409	updated poll
DELETE	/poll/{pollId}	no	Delete poll	200, 403, 404	deleted poll

Special functions

Method	Endpoint	Payload	Description	Return codes	Return value
POST	/poll/{pollId}/clone	no	Clone poll from {pollId}	201, 403, 404	cloned poll
POST	/poll/{pollId}/trash	no	Move to/remome from trash	200, 403, 404	updated poll
GET	/enum/poll	no	Get valid enums	200, 403, 404	array

Valid payloads

Add new poll

{
    "type": "datePoll",
    "title": "Poll Title"
}

Update poll

send the full or a partial structure

{
    "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

Default functions

Method	Endpoint	Payload	Description	Return codes	Return value
GET	/poll/{pollId}/options	no	Get poll options	200, 403, 404	array
POST	/poll/{pollId}/option	yes	Add new option	201, 403, 404, 409	added option
PUT	/option/{optionId}	yes	Update option	200, 403, 404	updated option
DELETE	/option/{optionId}	no	Delete option	200, 403, 404	deleted option

Special functions (no payloads)

Method	Endpoint	Description	Return codes	Return value
PUT	/option/{optionId}/confirm	Confirm/unconfirm option	200, 403, 404	confirmed option
PUT	/option/{optionId}/setorder/{order}	Set order (text poll)	200, 403, 404	array

Valid payloads

Add/update option (text poll)

{
    "pollOptionText": "Text of new option"
}

Add/update option (date poll)

{
	"timestamp": 1589195823,
    "duration": 1800
}

Keys and values

Key	Type	description
pollOptionText	String	poll text
timestamp	Integer	10 digit unix timestamp
duration	Integer	duration in seconds

Votes

Method	Endpoint	Description	Return codes
GET	/poll/{pollId}/votes	Get votes	200, 403, 404
POST	/vote	Set vote with Payload	200, 403, 404

set vote

{
    "optionId": 1,
    "setTo" :"yes"
}

Comments

Method	Endpoint	Description	Return codes
GET	/poll/{pollId}/comments	Get comments	200, 403, 404
POST	/comment	Add new comment with Payload	201, 403, 404
DELETE	/comment/{commentId}	Delete comment	200, 403, 404

Add comment

{
    "pollId": 1,
    "message": "Comment text"
}

Shares

Method	Endpoint	Description	Return codes
GET	/poll/{pollId}/shares	Get shares	200, 403, 404
GET	/share/{token}	Get share by token	200, 403, 404
POST	/share	Add new share with Payload	201, 403, 404
DELETE	/share/{token}	Delete share	200, 404, 409

Add share

public share

{
    "type": "public",
    "pollId": 1
}

user share

tbd

email share

tbd

contact share

tbd

Subscription

Method	Endpoint	Description	Return codes
GET	/poll/{pollId}/subscription	Get subscription status	200, 403, 404
PUT	/poll/{pollId}/subscription	Subcribe	201, 403
DELETE	/poll/{pollId}/subscription	unsubscribe	200, 403