Groups¶

Groups are used to select which people will go to which place.

GET /group/¶

Authenticated request

Return a list of the groups the user belongs or it’s the owner.

Header Authorization:
	Access token from /token/.
Status Codes:	200 – Success HTTP/1.1 200 OK Content-Type: application/json { "status": "OK", "groups": [ { "id": "<group id>" , "name": "<group name>", "admin": <true if the user is admin>}, ...] } 404 – User not found (via token) (`UserNotFoundException`) 412 – Authorization required (`AuthorizationRequiredException`)

POST /group/¶

Authenticated request

Create a new group. Once the group is created, the user becomes the administrator of the group.

Example request:

{ "name": "Name for the group" }

Header Authorization:
	Access token from /token/.
Status Codes:	200 – Success HTTP/1.1 200 OK Content-Type: application/json { "status": "OK", "id": <new group id> } 404 – User not found (via token) (`UserNotFoundException`) 412 – Authorization required (`AuthorizationRequiredException`) 412 – Account not verified (`AccountNotVerifiedException`)

PUT /group/(int: group_id)/¶

Authenticated request

Update group information. The user must be the administrator of the group to change any information. Partial requests are accepted and missing fields are not changed.

The administrator of the group can be changed by sending the “admin” field with the username of the new administrator.

Example request:

{ "name": "new group name": "admin": "newAdmin"}

Header Authorization:
	Access token from /token/.
Status Codes:	200 – Success 400 – Request not in JSON format (`RequestMustBeJSONException`) 403 – User is not the group administrator (`UserIsNotAdminException`) 404 – User not found (via token) (`UserNotFoundException`) 404 – New administrator does not exist (`NewMaintainerDoesNotExistException`) 412 – Authorization required (`AuthorizationRequiredException`)

DELETE /group/(int: group_id)/¶

Authenticated request

Delete a group. Only the administrator of the group can delete it.

Header Authorization:
Parameters:	group_id – The group Id
	Access token from /token/.
Status Codes:	200 – Success 403 – User is not the group administrator (`UserIsNotAdminException`) 404 – User not found (via token) (`UserNotFoundException`) 412 – Authorization required (`AuthorizationRequiredException`)

POST /group/(int: group_id)/users/¶

Authenticated request

Add users to the group. Only the group administrator can add users to their groups.

Parameters:	group_id – The group Id

Example request:

{ "usernames": ["<username>", "<username>", ...] }

Header Authorization:

Access token from /token/.

Status Codes:

200 –

Success. Users that couldn’t be found will be returned in the “not_found” field.

HTTP/1.1 200 OK
Content-Type: application/json

{ "status": "OK", "not_found": [<user>, <user>, ...] }

400 – Request not in JSON format (RequestMustBeJSONException)
403 – User is not the group administrator (UserIsNotAdminException)
404 – User not found (via token) (UserNotFoundException)
412 – Authorization required (AuthorizationRequiredException)

GET /group/(int: group_id)/users/¶

Authenticated request

Return a list of the users in the group. The user must be part of the group to request this list.

Header Authorization:
Parameters:	group_id – The group Id
	Access token from /token/.
Status Codes:	200 – Success HTTP/1.1 200 OK Content-Type: application/json { "status": "OK", "users": [ { "username": "<username>", "full_name": "<full name>"}, ...] } 403 – The user is not a member of the group (`UserIsNotMemberException`) 404 – User not found (via token) (`UserNotFoundException`) 404 – Group not found (`ElementNotFoundException`) 412 – Authorization required (`AuthorizationRequiredException`)

DELETE /group/(int: group_id)/places/(int: place_id)/¶

Authenticated request

Remove a place from the group. The user must be the group owner.

Header Authorization:
Parameters:	group_id – The group Id place_id – The place Id
	Access token from /token/.
Status Codes:	200 – Success 403 – User is not the group administrator (`UserIsNotAdminException`) 404 – User not found (via token) (`UserNotFoundException`) 404 – Group not found (`ElementNotFoundException`) 404 – Place is not part of the group (`ElementNotFoundException`) 412 – Authorization required (`AuthorizationRequiredException`)

GET /group/(int: group_id)/places/¶

Authenticated request

Return the list of places for the group. The user must be a member of the group the get the list of places.

Header Authorization:
Parameters:	group_id – The group Id
	Access token from /token/.
Status Codes:	200 – Success HTTP/1.1 200 OK Content-Type: application/json { "status": "OK", "places": [ { "id": "<place id>", "name": "<place name>"}, ...] } 403 – The user is not a member of the group (`UserIsNotMemberException`) 404 – User not found (via token) (`UserNotFoundException`) 404 – Group does not exist (`ElementNotFoundException`) 412 – Authorization required (`AuthorizationRequiredException`)

POST /group/(int: group_id)/places/¶

Authenticated request

Add a list of places to the group. The user must be the admin of the group to add a place; the place must belong to one of the group members to be able to be added to the group.

Header Authorization:
Parameters:	group_id – The group Id
	Access token from /token/.
Status Codes:	200 – Success. If there are any places that do not belong to group members, those will be returned in the “rejected” field; places that don’t exist will be returned in the “not_found” field. HTTP/1.1 200 OK Content-Type: application/json { "status": "OK", "rejected": [<place>, <place>, ...], "not_found": [<place>, <place>, ...] } 400 – Request not in JSON format (`RequestMustBeJSONException`) 403 – User is not the group administrator (`UserIsNotAdminException`) 404 – User not found (via token) (`UserNotFoundException`) 412 – Authorization required (`AuthorizationRequiredException`)