FORMAT: 1A HOST: http://luncho.io/ # Lunch-o Democratic Lunching. # 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. Once a token has been acquired, you must use it as a HTTP BasicAuth value: The token must be used in the username and the password will be ignored. All authenticated requests must authenticate the user in this form. ### 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" } + Response 404 (application/json) { "status": "ERROR", "error": "User does not exist" } ## 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" } ### Update information [POST] **Authenticated** Partial requests are valid (e.g., a request with a single "full\_name" will update only the full\_name for that user; a password change will require only the "password"field. + Request (application/json) { "full_name": "Full name", "password": "hash" } + Response 200 (application/json) { "status": "OK" } + Response 400 (application/json) { "status": "ERROR", "error": "Invalid token" } + Response 404 (application/json) { "status": "ERROR", "error": "User not found (via token)"} ### Remove user [DELETE] **Authenticated** User removal is only allowed to the user themselves or by a system admin. + 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 Places to have lunch. ## Places [/places/] **Authenticated** Retrieve the list of all places the user has access. This is directly tied to the Group management and will return all the places the user have access in their groups. ### Retrieval [GET] Return the list of all places in the system that the user have access. + Request (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/{placeId}/] Manage a single place. The user must be the maintainer of the place. + Parameters + placeId ... 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 404 (application/json) { "status": "ERROR", "error": "Place not found" } + 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" } + Response 404 (application/json) { "status": "ERROR", "error": "Place not found" } # Group Groups **Authenticated** 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 voted (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. + Response 200 (application/json) { "status": "OK", "groups": [{"id": 1, "name": "Group 1", "admin": true}, {"id": 2, "name": "Group 2", "admin": false}] } + 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) { "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/{groupId}/] **Authenticated** 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 + groupId ... The group ID. ### Update information [POST] + Request (application/json) { "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 404 (application/json) { "status": "ERROR", "error": "Group not found" } + Response 409 (application/json) { "status": "ERROR", "error": "New maintaner does not exist" } ### Remove group [DELETE] + 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 404 (application/json) { "status": "ERROR", "error": "Group not found" } ## Adding other users to the group [/group/{groupId}/users/] **Authenticated** Manages the users in the group. The only user that can do these kind of changes is the owner of the group. ### Get a list of members [GET] **Authenticated** + Responde 200 (application/json) { "status": "OK", "users": [ { "username": "", "full_name": ""}, ... ] } + Response 400 (application/json) { "status": "ERROR", "error": "Invalid token" } + Response 401 (application/json) { "status": "ERROR", "error": "User is not admin" } + Response 404 (application/json) { "status": "ERROR", "error": "Group not found" } ### Adding members [PUT] + Request (application/json) { "usernames": ["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 404 (application/json) { "status": "ERROR", "error": "Group not found" } ## Users in the group [/group/{groupId}/users/{username}/] Manage users in the group. The user (token owner) must be the maintainer of the group. + Parameters + groupId ... The group ID. + username ... User username. ### Remove user [DELETE] + 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 404 (application/json) { "status": "ERROR", "error": "Group not found" } + Response 412 (application/json) { "status": "ERROR", "error": "User is not a member of this group" } ## Places in the group [/group/{groupId}/places/] **Authenticated** The places the group has already selected as their prefered/nearby places for lunching. + Parameters + groupId ... The group ID. ### Retrieve the places for the group [GET] + Response 200 (application/json) { "status": "OK", "places": [ {"id": 1, "name": "Place 1", "id": 2, "name": "Place 2"} ] } + Response 400 (application/json) { "status": "ERROR", "error": "Invalid token" } + Response 404 (application/json) { "status": "ERROR", "error": "Group not found" } + Response 412 (application/json) { "status": "ERROR", "error": "User is not a member of this group" } ### Adding new places to a group [PUT] + Request (application/json) { "token": "userToken", "places": [1] } + Response 200 (application/json) { "status": "OK" } + Response 400 (application/json) { "status": "ERROR", "error": "Invalid token" } + Response 404 (application/json) { "status": "ERROR", "error": "Group not found" } + Response 409 (application/json) { "status": "ERROR", "error": "Place does not exist" } + Response 412 (application/json) { "status": "ERROR", "error": "User is not a member of this group" } ## Managing places in the group [/group/{groupId}/places/{placeId}] **Authenticated** ### Removing 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" } + Response 404 (application/json) { "status": "ERROR", "error": "Group or place not found" } # Group Voting User voting. ## Voting [/vote/{groupId}/] **Authenticated** 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. + Parameters + 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 404 (application/json) { "status": "ERROR", "error": "User didn't vote in this group today" }