Teams
Note:
There are three design decisions to call out:
(1) There is no concept of private teams.
(2) To manage membership we introduce MembershipInvitation and MembershipRequest objects. The former is made by a Team admin, the latter by a prospective Team member.
(3) We don't support an alternate user group in which the owner can unilaterally add members. To stream line membership acceptance we would bundle it with other steps such as account creation, terms of use acceptance, etc.
Permissions
| ACCESS_TYPE | Usage |
|---|---|
| UPDATE | Edit metadata. |
| MEMBERSHIP | Create membership invitation. Review membership invitations and membership requests for the team. Accept membership request. |
| DELETE | Delete team |
| SEND_MESSAGE | Send a message to all members of a team. |
| URI | Method | Request Param's | Request Body | Response Body | Description | Intended User (if specific) | Authority |
|---|---|---|---|---|---|---|---|
| /team | POST | Team | Team | Create team. Team ACL initially has two entries: (1) Creator has UPDATE, DELETE, MEMBERSHIP permissions; (2) Team has SEND_MESSAGE permissions. | Team admin | Authenticated users. | |
| /teams | GET | fragment, limit, offset, callback* | n/a | PaginatedResults<Team> | Get paginated list of teams, optionally filtered by the given name fragment. | Public | |
| /teams | GET | limit, offset, callback* | n/a | PaginatedResults<Team> | Get paginated list of teams. | Public | |
| /user/{id}/team | GET | limit, offset | n/a | PaginatedResults<Team> | Get a paginated list of teams to which the given user belongs. | Public | |
| /team/{id} | GET | n/a | Team | Get the metadata for the indicated team. | Public | ||
| /team/{id}/icon | GET | redirect | n/a | file | Download the icon indicated by the file handle ID in the 'icon' field of the Team metadata. If redirect=false parameter is included, then rather than redirecting to the download URL the service simply returns the redirect URL to the caller. | Public | |
| /team | PUT | Team | Team | Update the metadata for the team (not including membership). | Team admin | UPDATE permission | |
| /team/{id} | DELETE | n/a | n/a | Delete the indicated team. | Team admin | DELETE permission | |
/team/{teamId}/accessRequirement | GET | n/a | VariableContentPaginatedResults<AccessRequirement> | Get all the access requirements applied to the Team | Team admin | Public | |
/team/{teamId}/accessRequirementUnfulfilled | GET | n/a | VariableContentPaginatedResults<AccessRequirement> | Get all the access requirements for the Team unfulfilled by this user. | Prospective team member | Public | |
/team/{teamId}/accessApproval | GET | n/a | VariableContentPaginatedResults<AccessApproval> | Get all the access approvals for the Team. | ACT | ACT Membership | |
| /team/{id}/member/{principalId} | PUT | n/a | n/a | Adds a principal to the team. | Team admin or Prospective team member | Either:
| |
| /team/{id}/member/{principalId} | GET | n/a | TeamMember | Get the TeamMember object for the given team and user. | Team member | Public | |
| /team/{id}/member/{principalId}/permission | PUT | isAdmin | n/a | n/a | Set permissions for the given member of the given team. If 'isAdmin' is true then the user is given administrative permissions (the same as the creator's). If 'isAdmin' is false then the user's permissions are reduced to those of a basic member. | Team admin | UPDATE permission |
| /teamMembers/{id} | GET | fragment, limit, offset, callback* | n/a | PaginatedResults<TeamMember> | Get paginated list of members of the specified Team, optionally filtered by the given name fragment. The response body is a PaginatedList of TeamMember. | Public | |
| /team/{id}/member/{principalId} | DELETE | n/a | n/a | Remove principalId from team | Team Admin or Current Team Member | MEMBERSHIP permission on group OR user issuing request is the one being removed. | |
| /team/{id}/member/{principalId}/membershipStatus | GET | n/a | TeamMembershipStatus | Return status bundle, saying whether user is a team member, whether they have open invitations, requests, etc. | Any user | PUBLIC | |
| /membershipInvitation | POST | MembershipInvtnSubmission | MembershipInvtnSubmission | Invite someone to join the team. Note, the invitee list can include a group/team, as shorthand for all users in said group/team. | Team Admin | MEMBERSHIP permission on the team. | |
| /user/{id}/openInvitation | GET | teamId, limit, offset | n/a | PaginatedResults<MembershipInvitation> | Get a paginated list of all the open membership invitations extended to a user, optionally filtering by teamId. The list omits invitations from teams the user has already joined and omits invitations which have expired. | Invited User | PUBLIC |
/team/{id}/openInvitation | GET | inviteeId, limit, offset | n/a | PaginatedResults<MembershipInvtnSubmission> | Get a paginated list of all the open membership invitations extended by a Team, optionally filtering by inviteeId. The list omits invitations from teams the invitee has already joined and omits invitations which have expired. | Team admin | PUBLIC |
| /membershipInvitation/{id} | GET | n/a | MembershipInvtnSubmission | Retrieve the given membership invitation. | Team admin | MEMBERSHIP permission on the team. | |
| /membershipInvitation/{id} | DELETE | n/a | n/a | Delete (rescind) a membership invitation. | Team admin | MEMBERSHIP permission on the team. | |
| /membershipRequest | POST | MembershipRqstSubmission | MembershipRqstSubmission | Request by current user to be added to the team. | Prospective team member | Authenticated users. | |
| /team/{id}/openRequest | GET | requstorId, limit, offset | n/a | PaginatedResults<MembershipRequest> | Get a paginated list of open membership requests received by the indicated team, optionally filtering by requester. The list omits requests from requesters who have already joined the team and omits requests which have expired. | Team admin | MEMBERSHIP permission on the team. |
/user/{id}/openRequest | GET | teamId, limit, offset | n/a | PaginatedResults<MembershipRqustSubmission> | Get a paginated list of open membership requests created by a user, optionally filtering by Team. The list omits requests from requesters who have already joined the team and omits requests which have expired. | Prospective team member | PUBLIC |
| /membershipRequest/{id} | GET | n/a | MembershipRqstSubmission | Retrieve the given membership request. | Prospective team member | Must be user specified in membership request. | |
| /membershipRequest/{id} | DELETE | n/a | n/a | Delete the membership request. | Prospective team member | Must be user specified in membership request. |
* If 'callback' is provided then the result is formatted for JSONP, i.e. the response body is
<callback>(<result>);
where <callback> is the callback parameter and <result> is the JSON response otherwise returned by the service. Note that the URIs deviate a bit from our normal RESTful pattern. This is necessary to accommodate the limitations of url-pattern specification in web.xml and the need to make JSONP requirement that the request be publicly accessible (with no authentication header).