You can not select more than 25 topics
Topics must start with a letter or number, can include dashes ('-') and can be up to 35 characters long.
395 lines
9.1 KiB
395 lines
9.1 KiB
FORMAT: 1A |
|
HOST: http://pospichil.com/luncho/ |
|
|
|
# Lunch-o |
|
Lunching for Groups. |
|
|
|
# Group Users |
|
|
|
User and token management. |
|
|
|
## Token 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) |
|
|
|
{ "username": "username", "password": "hash" } |
|
|
|
+ Response 200 (application/json) |
|
|
|
{ "status": "OK", "token": "user-token" } |
|
|
|
+ Response 401 (application/json) |
|
|
|
{ "status": "ERROR", "error": "Invalid password" } |
|
|
|
|
|
## Users [/user/] |
|
|
|
APIs to add, update and remove users. |
|
|
|
### Creation [PUT] |
|
|
|
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) |
|
|
|
{ "username": "username", "full_name": "Full Name", "password": "hash" } |
|
|
|
+ Response 200 (application/json) |
|
|
|
{ "status": "OK" } |
|
|
|
+ Response 409 (application/json) |
|
|
|
{ "status": "ERROR", "error": "username already exists" } |
|
|
|
## Single User [/user/{username}/] |
|
|
|
Manage a single user. |
|
|
|
+ Parameters |
|
+ username ... Username used in the creation process. |
|
|
|
### 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" } |
|
|
|
+ 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 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" } |
|
|
|
+ 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 or not the same user" } |
|
|
|
# Group Places |
|
|
|
Retrieval and management (for admin users) for lunching. |
|
|
|
## Places [/places/] |
|
|
|
Retrieve the list of all places the user has access. |
|
|
|
### Retrieval [GET] |
|
|
|
Return the list of all places in the system. |
|
|
|
+ Resquest (application/json) |
|
|
|
{ "token": "userToken" } |
|
|
|
+ Response 200 (application/json) |
|
|
|
{ "status": "OK", "places": [{"name": "Place 1", "id": 1} |
|
{"name": "Place 2", "id": 2}} |
|
|
|
### Add a new place [PUT] |
|
|
|
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) |
|
|
|
{ "token": "userToken", "place": "Place Name" } |
|
|
|
+ Response 200 (application/json) |
|
|
|
{ "status": "OK", "id": 3 } |
|
|
|
+ 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": "Account not verified" } |
|
|
|
|
|
## Place management [/places/{id}/] |
|
|
|
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", "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" } |
|
|
|
### Remove a place [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" } |
|
|
|
# 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/{groupId}] |
|
|
|
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] } |
|
|
|
+ Response 200 (application/json) |
|
|
|
{ "status": "OK" } |
|
|
|
+ Response 400 (application/json) |
|
|
|
{ "status": "ERROR", "error": "Invalid token" } |
|
|
|
+ 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 |
|
recasted. |
|
|
|
+ Request (application/json) |
|
|
|
{ "token": "userToken" } |
|
|
|
+ Response 200 (application/json) |
|
|
|
{ "status": "OK" } |
|
|
|
+ Response 406 (application/json) |
|
|
|
{ "status": "ERROR", "error": "User didn't vote in this group today" }
|
|
|