Author: tchemit Date: 2014-05-16 14:25:22 +0200 (Fri, 16 May 2014) New Revision: 3957 Url: http://forge.chorem.org/projects/pollen/repository/revisions/3957 Log: begin of rest api Modified: trunk/src/site/rst/restApi.rst Modified: trunk/src/site/rst/restApi.rst =================================================================== --- trunk/src/site/rst/restApi.rst 2014-05-16 12:11:00 UTC (rev 3956) +++ trunk/src/site/rst/restApi.rst 2014-05-16 12:25:22 UTC (rev 3957) @@ -10,102 +10,1358 @@ Doc === -GET /v1/doc +GET /v1/doc +----------- +Abstract +~~~~~~~~ + +To Show this documentation page. + Auth ==== -PUT /v1/login -GET /v1/lostpassword/{token} -GET /v1/logout +PUT /v1/login +------------- +Abstract +~~~~~~~~ + +To log in. + +In +~~ + +- mandaTory parameter **login** +- mandaTory parameter **password** +- optional parameter **remberberMe** + +Validation +~~~~~~~~~~ + +- status 401 if bad authentication + +Out +~~~ + +:: + + { + id: "TokenId", + permission: "Token" + } + +A cookie named **pollenSession** with this data will be keep this data til you are logout. + +The cookie will be user for each request To log you in. + +GET /v1/lostpassword/{Token} +---------------------------- + +Abstract +~~~~~~~~ + +To ask a new password generation. + +In +~~ + +- mandaTory parameter **login** + +Validation +~~~~~~~~~~ + +- status 404 If login is not found + +FIXME Should return nothing (do not inform user the login does not exist). + +Out +~~~ + +None. + +GET /v1/logout +-------------- + +Abstract +~~~~~~~~ + +To log out from pollen. + +In +~~ + +None. + +Validation +~~~~~~~~~~ + +None. + +Out +~~~ + +None. The **pollenSession** cookie will be removed. + +Poll +==== + +GET /v1/polls/new +----------------- + +Abstract +~~~~~~~~ + +To get a empty poll with default create values. + +In +~~ + +None. + +Validation +~~~~~~~~~~ + +None. + +Out +~~~ + +:: + + { + "id" : null, + "permission" : null, + "creaTorName" : null, + "creaTorEmail" : null, + "title" : null, + "description" : null, + "beginChoiceDate" : null, + "endChoiceDate" : null, + "beginDate" : 1388530800000, + "endDate" : null, + "maxChoiceNumber" : 0, + "choiceAddAllowed" : false, + "anonymousVoteAllowed" : false, + "continuousResults" : false, + "voteCountingType" : 1, + "pollType" : "FREE", + "voteVisibility" : "EVERYBODY", + "commentVisibility" : "EVERYBODY", + "resultVisibility" : "EVERYBODY", + "persisted" : false + } + + +GET /v1/polls +------------- + +Abstract +~~~~~~~~ + +To get all polls (for admin usage only). + +In +~~ + +None. + +Validation +~~~~~~~~~~ + +- must be connected +- must be admin + +Out +~~~ + +:: + + [ + { + + } + ] + +GET /v1/polls/created +--------------------- + +Abstract +~~~~~~~~ + +Get all the created polls for a connected user. + +In +~~ + +Validation +~~~~~~~~~~ + +- need To be connected + +Out +~~~ + +A list of polls: + +:: + + [ + { poll1 }, + ... + ] + +GET /v1/polls/invited +--------------------- + +Abstract +~~~~~~~~ + +Get all the invited polls for a connected user. + +In +~~ + +Validation +~~~~~~~~~~ + +- need To be connected + +Out +~~~ + +A list of polls: + +:: + + [ + { poll1 }, + ... + ] + +GET /v1/polls/participated +-------------------------- + +Abstract +~~~~~~~~ + +Get all the participated polls for a connected user. + +In +~~ + +Validation +~~~~~~~~~~ + +- need To be connected + +Out +~~~ + +A list of polls: + +:: + + [ + { poll1 }, + ... + ] + +POST /v1/polls +-------------- + +Abstract +~~~~~~~~ + +To create a poll. + +In +~~ + +- mandaTory **poll** parameter with this format + +:: + + + { + "id" : null, + "permission" : null, + "creaTorName" : null, + "creaTorEmail" : null, + "title" : null, + "description" : null, + "beginChoiceDate" : null, + "endChoiceDate" : null, + "beginDate" : 1388530800000, + "endDate" : null, + "maxChoiceNumber" : 0, + "choiceAddAllowed" : false, + "anonymousVoteAllowed" : false, + "continuousResults" : false, + "voteCountingType" : 1, + "pollType" : "FREE", + "voteVisibility" : "EVERYBODY", + "commentVisibility" : "EVERYBODY", + "resultVisibility" : "EVERYBODY", + "persisted" : false + } + +- mandaTory **choices** paremeter + +:: + + [ + { + name: "", + choicetype: "", + description: "" + }, + ... + ] + +- optional **voterLists** parameter (only for none free polls) + +:: + + [ + { + name: "voterList1", + weight: 1.0, + member : + [ + { + name: "member1", + email: "member1@pollen.org", + weight: 1.0 + }, + ... + ] + } + ] + +Validation +~~~~~~~~~~ + +TODO + +Out +~~~ + +Created poll reference: + +:: + + { + id: "pollId", + permission: "Token To be able To edit again the poll" + } + +PUT /v1/polls/{pollId} +---------------------- + +Abstract +~~~~~~~~ + +Edit a poll. + +In +~~ + +- mandaTory **poll** parameter with this format + +:: + + { + "id" : null, + "permission" : null, + "creaTorName" : null, + "creaTorEmail" : null, + "title" : null, + "description" : null, + "beginChoiceDate" : null, + "endChoiceDate" : null, + "beginDate" : 1388530800000, + "endDate" : null, + "maxChoiceNumber" : 0, + "choiceAddAllowed" : false, + "anonymousVoteAllowed" : false, + "continuousResults" : false, + "voteCountingType" : 1, + "pollType" : "FREE", + "voteVisibility" : "EVERYBODY", + "commentVisibility" : "EVERYBODY", + "resultVisibility" : "EVERYBODY", + "persisted" : false + } + +- optional parameter **permission** (if user is connected no need) + +Validation +~~~~~~~~~~ + +Out +~~~ + +GET /v1/polls/{pollId} +---------------------- + +Abstract +~~~~~~~~ + +Get the poll of the given id. + +In +~~ + +None. + +Validation +~~~~~~~~~~ + +None. + +Out +~~~ + +A poll: + +:: + + { + "id" : null, + "permission" : null, + "creaTorName" : null, + "creaTorEmail" : null, + "title" : null, + "description" : null, + "beginChoiceDate" : null, + "endChoiceDate" : null, + "beginDate" : 1388530800000, + "endDate" : null, + "maxChoiceNumber" : 0, + "choiceAddAllowed" : false, + "anonymousVoteAllowed" : false, + "continuousResults" : false, + "voteCountingType" : 1, + "pollType" : "FREE", + "voteVisibility" : "EVERYBODY", + "commentVisibility" : "EVERYBODY", + "resultVisibility" : "EVERYBODY", + "persisted" : false + } + +DELETE /v1/polls/{pollId} +------------------------- + +Abstract +~~~~~~~~ + +To delete a poll. + +In +~~ + +None. + +Validation +~~~~~~~~~~ + +None. + +Out +~~~ + +None. + +POST /v1/polls/{pollId} +----------------------- + +Abstract +~~~~~~~~ + +To clone a poll. + +In +~~ + +None. + +Validation +~~~~~~~~~~ + +None. + +Out +~~~ + +Reference on cloned poll. + +GET /v1/polls/{pollId}/export +----------------------------- + +Abstract +~~~~~~~~ + +To export a poll. + +In +~~ + +None. + +Validation +~~~~~~~~~~ + +None. + +Out +~~~ + +Stream of the file. + +PUT /v1/polls/{pollId}/close +---------------------------- + +Abstract +~~~~~~~~ + +To close a poll. + +In +~~ + +None. + +Validation +~~~~~~~~~~ + +Out +~~~ + +None. + Choice ====== -GET /v1/polls/{pollId}/choices -POST /v1/polls/{pollId}/choices -GET /v1/polls/{pollId}/choices/{choiceId} -PUT /v1/polls/{pollId}/choices/{choiceId} -DELETE /v1/polls/{pollId}/choices/{choiceId} +GET /v1/polls/{pollId}/choices +------------------------------ +Abstract +~~~~~~~~ + +To get all choices of a poll. + +In +~~ + +Validation +~~~~~~~~~~ + +Out +~~~ + +POST /v1/polls/{pollId}/choices +------------------------------- + +Abstract +~~~~~~~~ + +To add a new choice on a poll. + +In +~~ + +Validation +~~~~~~~~~~ + +Out +~~~ + +GET /v1/polls/{pollId}/choices/{choiceId} +----------------------------------------- + +Abstract +~~~~~~~~ + +To get a choice. + +In +~~ + +Validation +~~~~~~~~~~ + +Out +~~~ + +PUT /v1/polls/{pollId}/choices/{choiceId} +----------------------------------------- + +Abstract +~~~~~~~~ + +To edit a choice. + +In +~~ + +Validation +~~~~~~~~~~ + +Out +~~~ + +DELETE /v1/polls/{pollId}/choices/{choiceId} +-------------------------------------------- + +Abstract +~~~~~~~~ + +To delete a choice. + +In +~~ + +Validation +~~~~~~~~~~ + +Out +~~~ + Comment ======= -GET /v1/polls/{pollId}/comments -POST /v1/polls/{pollId}/comments -GET /v1/polls/{pollId}/comments/{commentId} -PUT /v1/polls/{pollId}/comments/{commentId} -DELETE /v1/polls/{pollId}/comments/{commentId} +GET /v1/polls/{pollId}/comments +------------------------------- +Abstract +~~~~~~~~ + +To get all comments of a poll. + +In +~~ + +Validation +~~~~~~~~~~ + +Out +~~~ + + +POST /v1/polls/{pollId}/comments +-------------------------------- + +Abstract +~~~~~~~~ + +To add a comment on a poll. + +In +~~ + +Validation +~~~~~~~~~~ + +Out +~~~ + + +GET /v1/polls/{pollId}/comments/{commentId} +------------------------------------------- + +Abstract +~~~~~~~~ + +To get a comment. + +In +~~ + +Validation +~~~~~~~~~~ + +Out +~~~ + + +PUT /v1/polls/{pollId}/comments/{commentId} +------------------------------------------- + +Abstract +~~~~~~~~ + +To edit a comment. + +In +~~ + +Validation +~~~~~~~~~~ + +Out +~~~ + + +DELETE /v1/polls/{pollId}/comments/{commentId} +---------------------------------------------- + +Abstract +~~~~~~~~ + +To delete a comment. + +In +~~ + +Validation +~~~~~~~~~~ + +Out +~~~ + + FavoriteList ============ -GET /v1/favoriteLists -GET /v1/favoriteLists/{flId} -POST /v1/favoriteLists/{flId}/importCsv -POST /v1/favoriteLists/{flId}/importLdap -POST /v1/favoriteLists -PUT /v1/favoriteLists/{flId} -DELETE /v1/favoriteLists/{flId} -GET /v1/favoriteLists/{flId}/members -GET /v1/favoriteLists/{flId}/members/{mId} -POST /v1/favoriteLists/{flId}/members -PUT /v1/favoriteLists/{flId}/members/{mId} -DELETE /v1/favoriteLists/{flId}/members/{mId} +GET /v1/favoriteLists +--------------------- -Poll -==== +Abstract +~~~~~~~~ -GET /v1/polls/new -GET /v1/polls -GET /v1/polls/created -GET /v1/polls/invited -GET /v1/polls/participated -POST /v1/polls -GET /v1/polls/create -PUT /v1/polls/{pollId} -GET /v1/polls/{pollId} -DELETE /v1/polls/{pollId} -POST /v1/polls/{pollId} -GET /v1/polls/{pollId}/export -PUT /v1/polls/{pollId}/close +To get all favorite lists. +In +~~ + +Validation +~~~~~~~~~~ + +Out +~~~ + + +GET /v1/favoriteLists/{flId} +---------------------------- + +Abstract +~~~~~~~~ + +To get a favorite list. + +In +~~ + +Validation +~~~~~~~~~~ + +Out +~~~ + + +POST /v1/favoriteLists/{flId}/importCsv +--------------------------------------- + +Abstract +~~~~~~~~ + +To import a favorite list from a csv file. + +In +~~ + +Validation +~~~~~~~~~~ + +Out +~~~ + + +POST /v1/favoriteLists/{flId}/importLdap +---------------------------------------- + +Abstract +~~~~~~~~ + +To import a favorite list from a ldap. + +In +~~ + +Validation +~~~~~~~~~~ + +Out +~~~ + + +POST /v1/favoriteLists +---------------------- + +Abstract +~~~~~~~~ + +To create a new favorite list. + +In +~~ + +Validation +~~~~~~~~~~ + +Out +~~~ + + +PUT /v1/favoriteLists/{flId} +---------------------------- + +Abstract +~~~~~~~~ + +To edit a favorite list. + +In +~~ + +Validation +~~~~~~~~~~ + +Out +~~~ + + +DELETE /v1/favoriteLists/{flId} +------------------------------- + +Abstract +~~~~~~~~ + +To delete a favorite list. + +In +~~ + +Validation +~~~~~~~~~~ + +Out +~~~ + + +GET /v1/favoriteLists/{flId}/members +------------------------------------ + +Abstract +~~~~~~~~ + +To get all members of a favorite list. + +In +~~ + +Validation +~~~~~~~~~~ + +Out +~~~ + + +GET /v1/favoriteLists/{flId}/members/{mId} +------------------------------------------ + +Abstract +~~~~~~~~ + +To get a member of a favorite list. + +In +~~ + +Validation +~~~~~~~~~~ + +Out +~~~ + + +POST /v1/favoriteLists/{flId}/members +------------------------------------- + +Abstract +~~~~~~~~ + +To add a member in a favorite list. + +In +~~ + +Validation +~~~~~~~~~~ + +Out +~~~ + + +PUT /v1/favoriteLists/{flId}/members/{mId} +------------------------------------------ + +Abstract +~~~~~~~~ + +To edit a favorite list member. + +In +~~ + +Validation +~~~~~~~~~~ + +Out +~~~ + + +DELETE /v1/favoriteLists/{flId}/members/{mId} +--------------------------------------------- + +Abstract +~~~~~~~~ + +To delete a member from a favorite list. + +In +~~ + +Validation +~~~~~~~~~~ + +Out +~~~ + + PollenUser ========== -GET /v1/users -GET /v1/users/{userId} -POST /v1/users -PUT /v1/users/{userId} -DELETE /v1/users/{userId} -PUT /v1/users/{userId}?token={} +GET /v1/users +------------- +Abstract +~~~~~~~~ + +To get all users (only for admin). + +In +~~ + +Validation +~~~~~~~~~~ + +Out +~~~ + + +GET /v1/users/{userId} +---------------------- + +Abstract +~~~~~~~~ + +To get a user. + +In +~~ + +Validation +~~~~~~~~~~ + +Out +~~~ + + +POST /v1/users +-------------- + +Abstract +~~~~~~~~ + +To create a user. + +In +~~ + +Validation +~~~~~~~~~~ + +Out +~~~ + + +PUT /v1/users/{userId} +---------------------- + +Abstract +~~~~~~~~ + +To edit a user. + +In +~~ + +Validation +~~~~~~~~~~ + +Out +~~~ + + +DELETE /v1/users/{userId} +------------------------- + +Abstract +~~~~~~~~ + +To delete a user. + +In +~~ + +Validation +~~~~~~~~~~ + +Out +~~~ + + +PUT /v1/users/{userId}?Token={} +------------------------------- + +Abstract +~~~~~~~~ + +To validate email of a user. + +In +~~ + +Validation +~~~~~~~~~~ + +Out +~~~ + + VoteCounting ============ -GET /v1/polls/{pollId}/results +GET /v1/polls/{pollId}/results +------------------------------ +Abstract +~~~~~~~~ + +To get results of a poll. + +In +~~ + +Validation +~~~~~~~~~~ + +Out +~~~ + + VoterList ========= -PUT /v1/polls/{pollId}/favoriteLists/{flId} -GET /v1/polls/{pollId}/voterLists -GET /v1/polls/{pollId}/voterLists/{vlId} -POST /v1/polls/{pollId}/voterLists -PUT /v1/polls/{pollId}/voterLists/{vlId} -DELETE /v1/polls/{pollId}/voterLists/{vlId} +PUT /v1/polls/{pollId}/favoriteLists/{flId} +------------------------------------------- -GET /v1/polls/{pollId}/voterLists/{vlId}/members -GET /v1/polls/{pollId}/voterLists/{vlId}/members/{mId} -POST /v1/polls/{pollId}/voterLists/{vlId}/members -PUT /v1/polls/{pollId}/voterLists/{vlId}/members/{mId} -DELETE /v1/polls/{pollId}/voterLists/{vlId}/members/{mId} +Abstract +~~~~~~~~ +To create a voterList from a favorite list. + +In +~~ + +Validation +~~~~~~~~~~ + +Out +~~~ + + +GET /v1/polls/{pollId}/voterLists +--------------------------------- + +Abstract +~~~~~~~~ + +To get voter lists of a poll. + +In +~~ + +Validation +~~~~~~~~~~ + +Out +~~~ + + +GET /v1/polls/{pollId}/voterLists/{vlId} +---------------------------------------- + +Abstract +~~~~~~~~ + +To get a voter list. + +In +~~ + +Validation +~~~~~~~~~~ + +Out +~~~ + + +POST /v1/polls/{pollId}/voterLists +---------------------------------- + +Abstract +~~~~~~~~ + +To add a new voter list To a poll. + +In +~~ + +Validation +~~~~~~~~~~ + +Out +~~~ + + +PUT /v1/polls/{pollId}/voterLists/{vlId} +---------------------------------------- + +Abstract +~~~~~~~~ + +To edit a voter list. + +In +~~ + +Validation +~~~~~~~~~~ + +Out +~~~ + + +DELETE /v1/polls/{pollId}/voterLists/{vlId} +------------------------------------------- + +Abstract +~~~~~~~~ + +To delete a voter list. + +In +~~ + +Validation +~~~~~~~~~~ + +Out +~~~ + + +GET /v1/polls/{pollId}/voterLists/{vlId}/members +------------------------------------------------ + +Abstract +~~~~~~~~ + +To get all members of a voter list. + +In +~~ + +Validation +~~~~~~~~~~ + +Out +~~~ + + +GET /v1/polls/{pollId}/voterLists/{vlId}/members/{mId} +------------------------------------------------------ + +Abstract +~~~~~~~~ + +To get a member of a voter list. + +In +~~ + +Validation +~~~~~~~~~~ + +Out +~~~ + + +POST /v1/polls/{pollId}/voterLists/{vlId}/members +------------------------------------------------- + +Abstract +~~~~~~~~ + +To add a member To a voter list. + +In +~~ + +Validation +~~~~~~~~~~ + +Out +~~~ + + +PUT /v1/polls/{pollId}/voterLists/{vlId}/members/{mId} +------------------------------------------------------ + +Abstract +~~~~~~~~ + +To edit a member of a voter list. + +In +~~ + +Validation +~~~~~~~~~~ + +Out +~~~ + + +DELETE /v1/polls/{pollId}/voterLists/{vlId}/members/{mId} +--------------------------------------------------------- + +Abstract +~~~~~~~~ + +To delete a member from a voter list. + +In +~~ + +Validation +~~~~~~~~~~ + +Out +~~~ + + Vote ==== -GET /v1/polls/{pollId}/votes -PUT /v1/polls/{pollId}/votes -GET /v1/polls/{pollId}/votes/{voteId} -PUT /v1/polls/{pollId}/votes/{voteId} -DELETE /v1/polls/{pollId}/votes/{voteId} +GET /v1/polls/{pollId}/votes +---------------------------- + +Abstract +~~~~~~~~ + +To get all votes of a poll. + +In +~~ + +Validation +~~~~~~~~~~ + +Out +~~~ + + +PUT /v1/polls/{pollId}/votes +---------------------------- + +Abstract +~~~~~~~~ + +To add a vote To a poll. + +In +~~ + +Validation +~~~~~~~~~~ + +Out +~~~ + + +GET /v1/polls/{pollId}/votes/{voteId} +------------------------------------- + +Abstract +~~~~~~~~ + +To get a vote. + +In +~~ + +Validation +~~~~~~~~~~ + +Out +~~~ + + +PUT /v1/polls/{pollId}/votes/{voteId} +------------------------------------- + +Abstract +~~~~~~~~ + +To edit a vote. + +In +~~ + +Validation +~~~~~~~~~~ + +Out +~~~ + + +DELETE /v1/polls/{pollId}/votes/{voteId} +---------------------------------------- + +Abstract +~~~~~~~~ + +To delete a vote. + +In +~~ + +Validation +~~~~~~~~~~ + +Out +~~~ +