Author: tchemit Date: 2013-06-01 08:51:23 +0200 (Sat, 01 Jun 2013) New Revision: 3811 Url: http://chorem.org/projects/pollen/repository/revisions/3811 Log: refs #886: Design a REST API layer (start API doc) Added: trunk/src/site/rst/service.rst Modified: trunk/pollen-persistence/src/main/models/pollen.properties trunk/pollen-persistence/src/main/models/pollen.yamlobjectmodel Modified: trunk/pollen-persistence/src/main/models/pollen.properties =================================================================== --- trunk/pollen-persistence/src/main/models/pollen.properties 2013-05-31 15:52:55 UTC (rev 3810) +++ trunk/pollen-persistence/src/main/models/pollen.properties 2013-06-01 06:51:23 UTC (rev 3811) @@ -1,8 +1,8 @@ ### # #%L # Pollen :: Persistence -# $Id: pollen.properties 3700 2012-09-23 13:09:29Z tchemit $ -# $HeadURL: http://svn.chorem.org/svn/pollen/trunk/pollen-persistence/src/main/xmi/polle... $ +# $Id$ +# $HeadURL$ # %% # Copyright (C) 2009 - 2012 CodeLutin, Tony Chemit # %% Property changes on: trunk/pollen-persistence/src/main/models/pollen.properties ___________________________________________________________________ Added: svn:keywords + Author Date Id Revision HeadURL Added: svn:eol-style + native Property changes on: trunk/pollen-persistence/src/main/models/pollen.yamlobjectmodel ___________________________________________________________________ Added: svn:keywords + Author Date Id Revision HeadURL Added: svn:eol-style + native Added: trunk/src/site/rst/service.rst =================================================================== --- trunk/src/site/rst/service.rst (rev 0) +++ trunk/src/site/rst/service.rst 2013-06-01 06:51:23 UTC (rev 3811) @@ -0,0 +1,122 @@ +.. - +.. * #%L +.. * Pollen +.. * $Id$ +.. * $HeadURL$ +.. * %% +.. * Copyright (C) 2009 - 2013 CodeLutin, Tony Chemit +.. * %% +.. * This program is free software: you can redistribute it and/or modify +.. * it under the terms of the GNU Affero General Public License as published by +.. * the Free Software Foundation, either version 3 of the License, or +.. * (at your option) any later version. +.. * +.. * This program is distributed in the hope that it will be useful, +.. * but WITHOUT ANY WARRANTY; without even the implied warranty of +.. * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the +.. * GNU General Public License for more details. +.. * +.. * You should have received a copy of the GNU Affero General Public License +.. * along with this program. If not, see <http://www.gnu.org/licenses/>. +.. * #L% +.. - + +Pollen REST Service API +~~~~~~~~~~~~~~~~~~~~~~~ + +Pollen offers some public REST APIs to access to his data. + +APIS +==== + +Authentication +-------------- + +- lostpassword GET /lostpassword/email : AuthService.lostPassword(email) +- login POST /login {login/password} : AuthService.login(login, password) -> token +- logout GET /logout {login} AuthService.logout(login) + +User +---- + +- signin PUT /user {...} : UserService.createUser(...) -> User +- get user profile GET /user[/userId] UserService.getUser(userId) -> User +- edit user profile POST /user {[userId +] properties) UserService.editUser(User) -> User +- validate email GET /validateemail/token UserService.validateEmail(token) + +Voting List +----------- + +- create voting list PUT /votinglist {...} VotingListService.createVotingList(userId,...) -> VotingList +- get voting list GET /votinglist/votinglistId VotingListService.getVotingList(vlId) -> VotingList +- get user's list of voting list GET /votinglists VotingListService.getUserVotingLists(userId) -> VotingList[] +- edit voting list POST /votinglist {votinglistId,name, description, ..., but not voter} VotingListService.editVotingList(VotingList) -> VotingList +- delete voting list DELETE /votinglist/vlId VotingListService.deleteVotingList(vlId) +- add voter to voting list PUT /votinglist/voId/voter {...} VotingListService.addVoter(voId, Voter) -> Voter +- remove voter to voting list : DELETE /votinglist/{votinglistId}/voter/voterId VotingListService.removeVoter(voId, Voter) + +Poll +---- + +- list poll created: GET /user/userId/polls {filter=created} PollService.getPollCreated(userId) : Poll[] +- list poll participed: GET /user/userId/polls {filter=participated} PollService.getPollParticipated(userId) : PollId[] +- list poll invited: GET /user/userId/polls {filter=invited} PollService.getPollInvited(userId) : PollId[] +- create poll: PUT /poll {...} PollService.createPoll(User,Poll) -> Poll +- delete poll: DELETE /poll/{pollId} PollService.deletePoll(pollId) +- clone poll : PUT /poll/{fromPollId} ? PollService.clonePoll(fromPollId) -> Poll +- close poll : POST /poll/{pollId} {action=close} PollService.closePoll(pollId) +- export poll : GET /poll/{pollId} {action=export} PollService.exportPoll(pollId) ->File +- edit poll : POST /poll {...} PollService.editPoll(Poll) -> Poll +- import voting list : + +- add choice in poll: PUT /poll/{pollId}/choices {choice object} +- remove choice in poll: DELETE /poll/{pollId}/choices/{choiceId} + +- get poll's voters: GET /poll/{pollId}/voters +- add voter: PUT /poll/{pollId}/voters {voter object} +- remove voter: DELETE /poll/{pollId}/voters/{choiceId} + +# Give up this way +#- set poll property: ??? en fait, c'est un update partiel du poll ? dans ce cas, il faudrait savoir comment détecter une info non donnée d'une info effacée :/ sinon, c'est renvoyer toutes les infos du poll :/ +# - set poll name: ??? +# - set poll description: ??? +# - ... + +Voting +------ + +?- vote in poll for one choice: ??? +- get votes' poll: ??? +- vote for poll: ??? +- remove vote: ??? + +- get poll's comment: GET /poll/{pollId}/comments +- add comment: PUT /poll/{pollId}/comments {comment object} +- remove comment: DELETE /poll/{pollId}/comments/commentId + +Counting +-------- + +- winners list: GET /polls/{pollId}/result + +each counting type can have specific result type, how handle it ? (table, image, ...) : dans l'objet de retour, on peut avoir une entrée qui donne le type avant de donner le contenu ? + +Security +-------- + +See how to apply security, previous token way is a good choice (one token for poll, one token for user) + + +Idées / Questions +----------------- + +- ne pas utiliser directement un blob mais un lien vers une table qui gère les blob (BlobEntity) +- dans les urls, faut-il mettre du pluriel ou du singulier ? /user/ ou /users/ ? (YM : plutot pour le pluriel) + +Security +======== + +We are using a security token for authenticated user given by the login request, +keep it until you want need it... + +We should regenerate it at each request, and you should get it back then ? Property changes on: trunk/src/site/rst/service.rst ___________________________________________________________________ Added: svn:keywords + Author Date Id Revision HeadURL Added: svn:eol-style + native