|
|
|
@ -4,35 +4,39 @@ HOST: http://pospichil.com/luncho/
|
|
|
|
|
# Lunch-o |
|
|
|
|
Lunching for Groups. |
|
|
|
|
|
|
|
|
|
# Group Tokens |
|
|
|
|
Requesting access tokens. |
|
|
|
|
# Group Users |
|
|
|
|
|
|
|
|
|
User and token management. |
|
|
|
|
|
|
|
|
|
## Token access [/token/] |
|
|
|
|
Request an access token. |
|
|
|
|
|
|
|
|
|
Request an access token. Almost all requests from here will require that a |
|
|
|
|
token is provided; this API will return the required token, which will |
|
|
|
|
identify the user in further requests. |
|
|
|
|
|
|
|
|
|
### Request a token [POST] |
|
|
|
|
+ Request (application/json) |
|
|
|
|
|
|
|
|
|
+ Body |
|
|
|
|
+ Request (application/json) |
|
|
|
|
|
|
|
|
|
{ "username": "username", "password": "hash" } |
|
|
|
|
{ "username": "username", "password": "hash" } |
|
|
|
|
|
|
|
|
|
+ Response 200 (application/json) |
|
|
|
|
|
|
|
|
|
{ "status": "OK", "token": "user-token" } |
|
|
|
|
|
|
|
|
|
+ Response 403 (application/json) |
|
|
|
|
|
|
|
|
|
+ Response 401 (application/json) |
|
|
|
|
|
|
|
|
|
{ "status": "ERROR", "error": "Invalid password" } |
|
|
|
|
|
|
|
|
|
|
|
|
|
|
# Group Users |
|
|
|
|
## Users [/user/] |
|
|
|
|
|
|
|
|
|
User management. |
|
|
|
|
APIs to add, update and remove users. |
|
|
|
|
|
|
|
|
|
## Users [/user/] |
|
|
|
|
### Creation [PUT] |
|
|
|
|
|
|
|
|
|
### Creation [POST] |
|
|
|
|
After a user created an account, it needs to be verified. Unverified users are |
|
|
|
|
forbidden to create new groups. They can still vote, though. |
|
|
|
|
|
|
|
|
|
+ Request (application/json) |
|
|
|
|
|
|
|
|
@ -55,6 +59,10 @@ Manage a single user.
|
|
|
|
|
|
|
|
|
|
### Update information [POST] |
|
|
|
|
|
|
|
|
|
Partial requests are valid (e.g., a request with a single "full\_name" -- and |
|
|
|
|
"token", obviously -- will update only the full\_name for that user; a password |
|
|
|
|
change will require only the "token" and "password" fields. |
|
|
|
|
|
|
|
|
|
+ Request (application/json) |
|
|
|
|
|
|
|
|
|
{ "token": "userToken", "full_name": "Full name", "password": "hash" } |
|
|
|
@ -63,17 +71,19 @@ Manage a single user.
|
|
|
|
|
|
|
|
|
|
{ "status": "OK" } |
|
|
|
|
|
|
|
|
|
+ Response 401 (application/json) |
|
|
|
|
+ Response 400 (application/json) |
|
|
|
|
|
|
|
|
|
{ "status": "ERROR", "error": "Invalid token" } |
|
|
|
|
|
|
|
|
|
+ Response 403 (application/json) |
|
|
|
|
+ Response 401 (application/json) |
|
|
|
|
|
|
|
|
|
{ "status": "ERROR", "error": "User is not admin or not the same user" } |
|
|
|
|
|
|
|
|
|
|
|
|
|
|
### Remove user [DELETE] |
|
|
|
|
|
|
|
|
|
User removal is only allowed to the user themselves or by a system admin. |
|
|
|
|
|
|
|
|
|
+ Request (application/json) |
|
|
|
|
|
|
|
|
|
{ "token": "userToken" } |
|
|
|
@ -82,15 +92,16 @@ Manage a single user.
|
|
|
|
|
|
|
|
|
|
{ "status": "OK" } |
|
|
|
|
|
|
|
|
|
+ Response 401 (application/json) |
|
|
|
|
+ Response 400 (application/json) |
|
|
|
|
|
|
|
|
|
{ "status": "ERROR", "error": "Invalid token" } |
|
|
|
|
|
|
|
|
|
+ Response 403 (application/json) |
|
|
|
|
+ Response 401 (application/json) |
|
|
|
|
|
|
|
|
|
{ "status": "ERROR", "error": "User is not admin or not the same user" } |
|
|
|
|
|
|
|
|
|
# Group Places |
|
|
|
|
|
|
|
|
|
Retrieval and management (for admin users) for lunching. |
|
|
|
|
|
|
|
|
|
## Places [/places/] |
|
|
|
@ -99,7 +110,7 @@ Retrieve the list of all places the user has access.
|
|
|
|
|
|
|
|
|
|
### Retrieval [GET] |
|
|
|
|
|
|
|
|
|
Retrieve the list of places. |
|
|
|
|
Return the list of all places in the system. |
|
|
|
|
|
|
|
|
|
+ Resquest (application/json) |
|
|
|
|
|
|
|
|
@ -112,7 +123,9 @@ Retrieve the list of places.
|
|
|
|
|
|
|
|
|
|
### Add a new place [PUT] |
|
|
|
|
|
|
|
|
|
Add a new place. The user must be admin to do so. |
|
|
|
|
Add a new place. Once the place is created, the user becomes the "maintainer" |
|
|
|
|
of the place and only this user will be allowed to change any information about |
|
|
|
|
it. |
|
|
|
|
|
|
|
|
|
+ Request (application/json) |
|
|
|
|
|
|
|
|
@ -122,40 +135,52 @@ Add a new place. The user must be admin to do so.
|
|
|
|
|
|
|
|
|
|
{ "status": "OK", "id": 3 } |
|
|
|
|
|
|
|
|
|
+ Response 401 (application/json) |
|
|
|
|
+ Response 400 (application/json) |
|
|
|
|
|
|
|
|
|
{ "status": "ERROR", "error": "Invalid token" } |
|
|
|
|
|
|
|
|
|
+ Response 403 (application/json) |
|
|
|
|
+ Response 401 (application/json) |
|
|
|
|
|
|
|
|
|
{ "status": "ERROR", "error": "User is not admin" } |
|
|
|
|
|
|
|
|
|
+ Response 412 (application/json) |
|
|
|
|
|
|
|
|
|
{ "status": "ERROR", "error": "Account not verified" } |
|
|
|
|
|
|
|
|
|
|
|
|
|
|
## Place management [/places/{id}/] |
|
|
|
|
|
|
|
|
|
Manage a single place. The user must be admin. |
|
|
|
|
Manage a single place. The user must be the maintainer of the place. |
|
|
|
|
|
|
|
|
|
+ Parameters |
|
|
|
|
+ id ... The place id. |
|
|
|
|
|
|
|
|
|
### Edit a place [POST] |
|
|
|
|
|
|
|
|
|
Editing a place works like user information: only the fields that will be |
|
|
|
|
changed are required. Passing the "maintainer" will tranfer the maintenance |
|
|
|
|
ownership to another user, immediatelly. |
|
|
|
|
|
|
|
|
|
+ Request (application/json) |
|
|
|
|
|
|
|
|
|
{ "token": "userToken", "name": "Place 3" } |
|
|
|
|
{ "token": "userToken", "name": "Place 3", "maintainer": "username"} |
|
|
|
|
|
|
|
|
|
+ Response 200 (application/json) |
|
|
|
|
|
|
|
|
|
{ "status": "OK" } |
|
|
|
|
|
|
|
|
|
+ Response 401 (application/json) |
|
|
|
|
+ Response 400 (application/json) |
|
|
|
|
|
|
|
|
|
{ "status": "ERROR", "error": "Invalid token" } |
|
|
|
|
|
|
|
|
|
+ Response 403 (application/json) |
|
|
|
|
+ Response 401 (application/json) |
|
|
|
|
|
|
|
|
|
{ "status": "ERROR", "error": "User is not admin" } |
|
|
|
|
|
|
|
|
|
+ Response 409 (application/json) |
|
|
|
|
|
|
|
|
|
{ "status": "ERROR", "error": "New maintaner does not exist" } |
|
|
|
|
|
|
|
|
|
### Remove a place [DELETE] |
|
|
|
|
|
|
|
|
|
+ Request (application/json) |
|
|
|
@ -166,23 +191,164 @@ Manage a single place. The user must be admin.
|
|
|
|
|
|
|
|
|
|
{ "status": "OK" } |
|
|
|
|
|
|
|
|
|
+ Response 401 (application/json) |
|
|
|
|
+ Response 400 (application/json) |
|
|
|
|
|
|
|
|
|
{ "status": "ERROR", "error": "Invalid token" } |
|
|
|
|
|
|
|
|
|
+ Response 403 (application/json) |
|
|
|
|
+ Response 401 (application/json) |
|
|
|
|
|
|
|
|
|
{ "status": "ERROR", "error": "User is not admin" } |
|
|
|
|
|
|
|
|
|
# Group Groups |
|
|
|
|
|
|
|
|
|
Groups are used to combine a group of users and their favorite places. A location |
|
|
|
|
will be considered "selected" when all users in that group have vote (or |
|
|
|
|
abstain in voting). |
|
|
|
|
|
|
|
|
|
## Groups [/groups/] |
|
|
|
|
|
|
|
|
|
Group management. Only users with verified accounts can create new groups. Once |
|
|
|
|
a group is created, the user becomes the "maintainer" of the group and only this |
|
|
|
|
user can edit group information, remove the group, add and remove people from the |
|
|
|
|
group. |
|
|
|
|
|
|
|
|
|
### Getting groups [GET] |
|
|
|
|
|
|
|
|
|
Return groups in the system. Only groups in which the user belongs will be returned. |
|
|
|
|
|
|
|
|
|
+ Request (application/json) |
|
|
|
|
|
|
|
|
|
{ "token": "userToken" } |
|
|
|
|
|
|
|
|
|
+ Response 200 (application/json) |
|
|
|
|
|
|
|
|
|
{ "status": "OK", "groups": [{"id": 1, "name": "Group 1"}, |
|
|
|
|
{"id": 2, "name": "Group 2"}] } |
|
|
|
|
|
|
|
|
|
+ Response 400 (application/json) |
|
|
|
|
|
|
|
|
|
{ "status": "ERROR", "error": "Invalid token" } |
|
|
|
|
|
|
|
|
|
### Create a group [PUT] |
|
|
|
|
|
|
|
|
|
The user will become the maintainer of the group once it is created. |
|
|
|
|
|
|
|
|
|
+ Request (application/json) |
|
|
|
|
|
|
|
|
|
{ "token": "userToken", "name": "Group name" } |
|
|
|
|
|
|
|
|
|
+ Response 200 (application/json) |
|
|
|
|
|
|
|
|
|
{ "status": "OK", "id": 3 } |
|
|
|
|
|
|
|
|
|
+ Response 400 (application/json) |
|
|
|
|
|
|
|
|
|
{ "status": "ERROR", "error": "Invalid token" } |
|
|
|
|
|
|
|
|
|
+ Response 412 (application/json) |
|
|
|
|
|
|
|
|
|
{ "status": "ERROR", "error": "Account not verified" } |
|
|
|
|
|
|
|
|
|
## Group management [/group/{id}/] |
|
|
|
|
|
|
|
|
|
Only the maintainer of the group can change the information for the group. As usual, |
|
|
|
|
only the required fields are necessary. Passing "maintainer" will change the |
|
|
|
|
maintenance ownership to another user, immediatelly. |
|
|
|
|
|
|
|
|
|
+ Parameter |
|
|
|
|
+ id ... The group ID. |
|
|
|
|
|
|
|
|
|
### Update information [POST] |
|
|
|
|
|
|
|
|
|
+ Request (application/json) |
|
|
|
|
|
|
|
|
|
{ "token": "userToken", "name": "Group name", "maintainer": "username" } |
|
|
|
|
|
|
|
|
|
+ Response 200 (application/json) |
|
|
|
|
|
|
|
|
|
{ "status": "OK" } |
|
|
|
|
|
|
|
|
|
+ Response 400 (application/json) |
|
|
|
|
|
|
|
|
|
{ "status": "ERROR", "error": "Invalid token" } |
|
|
|
|
|
|
|
|
|
+ Response 401 (application/json) |
|
|
|
|
|
|
|
|
|
{ "status": "ERROR", "error": "User is not admin" } |
|
|
|
|
|
|
|
|
|
+ Response 409 (application/json) |
|
|
|
|
|
|
|
|
|
{ "status": "ERROR", "error": "New maintaner does not exist" } |
|
|
|
|
|
|
|
|
|
### Adding members [PUT] |
|
|
|
|
|
|
|
|
|
+ Request (application/json) |
|
|
|
|
|
|
|
|
|
{ "token": "userToken", "usernames": ["username"] } |
|
|
|
|
|
|
|
|
|
### Remove group [DELETE] |
|
|
|
|
|
|
|
|
|
+ Request (application/json) |
|
|
|
|
|
|
|
|
|
{ "token": "userToken", "name": "Group name", "maintainer": "username" } |
|
|
|
|
|
|
|
|
|
+ Response 200 (application/json) |
|
|
|
|
|
|
|
|
|
{ "status": "OK" } |
|
|
|
|
|
|
|
|
|
+ Response 400 (application/json) |
|
|
|
|
|
|
|
|
|
{ "status": "ERROR", "error": "Invalid token" } |
|
|
|
|
|
|
|
|
|
+ Response 401 (application/json) |
|
|
|
|
|
|
|
|
|
{ "status": "ERROR", "error": "User is not admin" } |
|
|
|
|
|
|
|
|
|
## Users in the group [/group/{id}/username/] |
|
|
|
|
|
|
|
|
|
Manage users in the group. The user (token owner) must be the maintainer of the |
|
|
|
|
group. |
|
|
|
|
|
|
|
|
|
+ Parameter |
|
|
|
|
+ id ... The group ID. |
|
|
|
|
|
|
|
|
|
### Remove user [DELETE] |
|
|
|
|
|
|
|
|
|
+ Request (application/json) |
|
|
|
|
|
|
|
|
|
{ "token": "userToken" } |
|
|
|
|
|
|
|
|
|
+ Response 200 (application/json) |
|
|
|
|
|
|
|
|
|
{ "status": "OK" } |
|
|
|
|
|
|
|
|
|
+ Response 400 (application/json) |
|
|
|
|
|
|
|
|
|
{ "status": "ERROR", "error": "Invalid token" } |
|
|
|
|
|
|
|
|
|
+ Response 401 (application/json) |
|
|
|
|
|
|
|
|
|
{ "status": "ERROR", "error": "User is not admin" } |
|
|
|
|
|
|
|
|
|
+ Response 412 (application/json) |
|
|
|
|
|
|
|
|
|
{ "status": "ERROR", "error": "User is not a member of this group" } |
|
|
|
|
|
|
|
|
|
# Group Voting |
|
|
|
|
|
|
|
|
|
User voting. |
|
|
|
|
|
|
|
|
|
## Voting [/vote/] |
|
|
|
|
## Voting [/vote/{groupId}] |
|
|
|
|
|
|
|
|
|
Make a vote for the day. The day is controlled by the server itself. If a vote has been cast |
|
|
|
|
but later removed, the server will also |
|
|
|
|
Make a vote for the day (controlled by the server). The user must selected in |
|
|
|
|
which group they are voting, which will block voting in any other groups, unless |
|
|
|
|
the vote is removed; voting in the same group again will only update the vote. |
|
|
|
|
|
|
|
|
|
+ Parameter |
|
|
|
|
+ groupId ... The group in which the user wants to vote |
|
|
|
|
|
|
|
|
|
### Cast a vote [POST] |
|
|
|
|
|
|
|
|
|
+ Request (application/json) |
|
|
|
|
|
|
|
|
|
{ "token": "userToken", "choices": [1, 2, 3] } |
|
|
|
@ -191,18 +357,26 @@ but later removed, the server will also
|
|
|
|
|
|
|
|
|
|
{ "status": "OK" } |
|
|
|
|
|
|
|
|
|
+ Response 401 (application/json) |
|
|
|
|
+ Response 400 (application/json) |
|
|
|
|
|
|
|
|
|
{ "status": "ERROR", "error": "Invalid token" } |
|
|
|
|
|
|
|
|
|
+ Response 403 (application/json) |
|
|
|
|
+ Response 401 (application/json) |
|
|
|
|
|
|
|
|
|
{ "status": "ERROR", "error": "Casted vote was removed" } |
|
|
|
|
|
|
|
|
|
+ Response 403 (application/json) |
|
|
|
|
|
|
|
|
|
{ "status": "ERROR", "error": "User does not belong to this group" } |
|
|
|
|
|
|
|
|
|
+ Response 409 (application/json) |
|
|
|
|
|
|
|
|
|
{ "status": "ERROR", "error": "Vote for place %d appeared more than once" } |
|
|
|
|
|
|
|
|
|
+ Response 410 (application/json) |
|
|
|
|
|
|
|
|
|
{ "status": "ERROR", "error": "User already voted for a group today" } |
|
|
|
|
|
|
|
|
|
### Remove a vote [DELETE] |
|
|
|
|
|
|
|
|
|
Remove a vote for the day. Once a vote has been removed, it can't be |
|
|
|
@ -215,4 +389,7 @@ recasted.
|
|
|
|
|
+ Response 200 (application/json) |
|
|
|
|
|
|
|
|
|
{ "status": "OK" } |
|
|
|
|
|
|
|
|
|
|
|
|
|
|
+ Response 406 (application/json) |
|
|
|
|
|
|
|
|
|
{ "status": "ERROR", "error": "User didn't vote in this group today" } |
|
|
|
|