Browse Source

updated documentation with groups

master
Julio Biason 11 years ago
parent
commit
f809e727b4
  1. 241
      apiary.apib

241
apiary.apib

@ -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" }

Loading…
Cancel
Save