Merge pull request #2397 from rdmchr/update-teams-doc

Overhauling the teams documentation

app/controllers/api/teams.php

@@ -113,9 +113,9 @@ App::get('/v1/teams')
     ->label('sdk.response.code', Response::STATUS_CODE_OK)
     ->label('sdk.response.type', Response::CONTENT_TYPE_JSON)
     ->label('sdk.response.model', Response::MODEL_TEAM_LIST)
-    ->param('search', '', new Text(256), 'Search term to filter your list results. Max length: 256 chars.', true)
-    ->param('limit', 25, new Range(0, 100), 'Results limit value. By default will return maximum 25 results. Maximum of 100 results allowed per request.', true)
-    ->param('offset', 0, new Range(0, 2000), 'Results offset. The default value is 0. Use this param to manage pagination.', true)
+    ->param('search', '', new Text(256), 'Search term to filter results. Max length: 256 chars.', true)
+    ->param('limit', 25, new Range(0, 100), 'Limit how many results will be returned. Returns up to 25 results by default. Maximum of 100 results allowed per request.', true)
+    ->param('offset', 0, new Range(0, 2000), 'Results offset. The default value is 0. Use this value to manage pagination.', true)
     ->param('orderType', 'ASC', new WhiteList(['ASC', 'DESC'], true), 'Order result by ASC or DESC order.', true)
     ->inject('response')
     ->inject('projectDB')
@@ -150,7 +150,7 @@ App::get('/v1/teams/:teamId')
     ->label('sdk.response.code', Response::STATUS_CODE_OK)
     ->label('sdk.response.type', Response::CONTENT_TYPE_JSON)
     ->label('sdk.response.model', Response::MODEL_TEAM)
-    ->param('teamId', '', new UID(), 'Team unique ID.')
+    ->param('teamId', '', new UID(), 'Team ID.')
     ->inject('response')
     ->inject('projectDB')
     ->action(function ($teamId, $response, $projectDB) {
@@ -178,8 +178,8 @@ App::put('/v1/teams/:teamId')
     ->label('sdk.response.code', Response::STATUS_CODE_OK)
     ->label('sdk.response.type', Response::CONTENT_TYPE_JSON)
     ->label('sdk.response.model', Response::MODEL_TEAM)
-    ->param('teamId', '', new UID(), 'Team unique ID.')
-    ->param('name', null, new Text(128), 'Team name. Max length: 128 chars.')
+    ->param('teamId', '', new UID(), 'Team ID.')
+    ->param('name', null, new Text(128), 'New team name. Max length: 128 chars.')
     ->inject('response')
     ->inject('projectDB')
     ->action(function ($teamId, $name, $response, $projectDB) {
@@ -214,7 +214,7 @@ App::delete('/v1/teams/:teamId')
     ->label('sdk.description', '/docs/references/teams/delete-team.md')
     ->label('sdk.response.code', Response::STATUS_CODE_NOCONTENT)
     ->label('sdk.response.model', Response::MODEL_NONE)
-    ->param('teamId', '', new UID(), 'Team unique ID.')
+    ->param('teamId', '', new UID(), 'Team ID.')
     ->inject('response')
     ->inject('projectDB')
     ->inject('events')
@@ -260,11 +260,11 @@ App::post('/v1/teams/:teamId/memberships')
     ->label('sdk.response.type', Response::CONTENT_TYPE_JSON)
     ->label('sdk.response.model', Response::MODEL_MEMBERSHIP)
     ->label('abuse-limit', 10)
-    ->param('teamId', '', new UID(), 'Team unique ID.')
-    ->param('email', '', new Email(), 'New team member email.')
-    ->param('roles', [], new ArrayList(new Key()), 'Array of strings. Use this param to set the user roles in the team. A role can be any string. Learn more about [roles and permissions](/docs/permissions). Max length for each role is 32 chars.')
+    ->param('teamId', '', new UID(), 'Team ID.')
+    ->param('email', '', new Email(), 'Email address of the new team member.')
+    ->param('roles', [], new ArrayList(new Key()), 'An array of strings. Use this param to set the user roles in the team. A role can be any string. Learn more about [roles and permissions](/docs/permissions). Max length for each role is 32 chars.')
     ->param('url', '', function ($clients) { return new Host($clients); }, 'URL to redirect the user back to your app from the invitation email.  Only URLs from hostnames in your project platform list are allowed. This requirement helps to prevent an [open redirect](https://cheatsheetseries.owasp.org/cheatsheets/Unvalidated_Redirects_and_Forwards_Cheat_Sheet.html) attack against your project API.', false, ['clients']) // TODO add our own built-in confirm page
-    ->param('name', '', new Text(128), 'New team member name. Max length: 128 chars.', true)
+    ->param('name', '', new Text(128), 'Name of the new team member. Max length: 128 chars.', true)
     ->inject('response')
     ->inject('project')
     ->inject('user')
@@ -472,9 +472,9 @@ App::patch('/v1/teams/:teamId/memberships/:membershipId')
     ->label('sdk.response.code', Response::STATUS_CODE_OK)
     ->label('sdk.response.type', Response::CONTENT_TYPE_JSON)
     ->label('sdk.response.model', Response::MODEL_MEMBERSHIP)
-    ->param('teamId', '', new UID(), 'Team unique ID.')
+    ->param('teamId', '', new UID(), 'Team ID.')
     ->param('membershipId', '', new UID(), 'Membership ID.')
-    ->param('roles', [], new ArrayList(new Key()), 'Array of strings. Use this param to set the user roles in the team. A role can be any string. Learn more about [roles and permissions](/docs/permissions). Max length for each role is 32 chars.')
+    ->param('roles', [], new ArrayList(new Key()), 'An array of strings. Use this param to set the user\'s roles in the team. A role can be any string. Learn more about [roles and permissions](/docs/permissions). Max length for each role is 32 chars.')
     ->inject('request')
     ->inject('response')
     ->inject('user')
@@ -534,11 +534,11 @@ App::get('/v1/teams/:teamId/memberships')
     ->label('sdk.response.code', Response::STATUS_CODE_OK)
     ->label('sdk.response.type', Response::CONTENT_TYPE_JSON)
     ->label('sdk.response.model', Response::MODEL_MEMBERSHIP_LIST)
-    ->param('teamId', '', new UID(), 'Team unique ID.')
-    ->param('search', '', new Text(256), 'Search term to filter your list results. Max length: 256 chars.', true)
-    ->param('limit', 25, new Range(0, 100), 'Results limit value. By default will return maximum 25 results. Maximum of 100 results allowed per request.', true)
-    ->param('offset', 0, new Range(0, 2000), 'Results offset. The default value is 0. Use this param to manage pagination.', true)
-    ->param('orderType', 'ASC', new WhiteList(['ASC', 'DESC'], true), 'Order result by ASC or DESC order.', true)
+    ->param('teamId', '', new UID(), 'Team ID.')
+    ->param('search', '', new Text(256), 'Search term to filter your results. Max length: 256 chars.', true)
+    ->param('limit', 25, new Range(0, 100), 'Limit how many results will be returned. By default will return a maximum of 25 results. Maximum of 100 results allowed per request.', true)
+    ->param('offset', 0, new Range(0, 2000), 'Results offset. The default value is 0. Use this value to manage pagination.', true)
+    ->param('orderType', 'ASC', new WhiteList(['ASC', 'DESC'], true), 'Order results by ASC or DESC order.', true)
     ->inject('response')
     ->inject('projectDB')
     ->action(function ($teamId, $search, $limit, $offset, $orderType, $response, $projectDB) {
@@ -588,9 +588,9 @@ App::patch('/v1/teams/:teamId/memberships/:membershipId/status')
     ->label('sdk.response.code', Response::STATUS_CODE_OK)
     ->label('sdk.response.type', Response::CONTENT_TYPE_JSON)
     ->label('sdk.response.model', Response::MODEL_MEMBERSHIP)
-    ->param('teamId', '', new UID(), 'Team unique ID.')
+    ->param('teamId', '', new UID(), 'Team ID.')
     ->param('membershipId', '', new UID(), 'Membership ID.')
-    ->param('userId', '', new UID(), 'User unique ID.')
+    ->param('userId', '', new UID(), 'User ID.')
     ->param('secret', '', new Text(256), 'Secret key.')
     ->inject('request')
     ->inject('response')
@@ -734,7 +734,7 @@ App::delete('/v1/teams/:teamId/memberships/:membershipId')
     ->label('sdk.description', '/docs/references/teams/delete-team-membership.md')
     ->label('sdk.response.code', Response::STATUS_CODE_NOCONTENT)
     ->label('sdk.response.model', Response::MODEL_NONE)
-    ->param('teamId', '', new UID(), 'Team unique ID.')
+    ->param('teamId', '', new UID(), 'Team ID.')
     ->param('membershipId', '', new UID(), 'Membership ID.')
     ->inject('response')
     ->inject('projectDB')

docs/references/teams/create-team-membership.md

@@ -1,5 +1,5 @@
-Use this endpoint to invite a new member to join your team. If initiated from Client SDK, an email with a link to join the team will be sent to the new member's email address if the member doesn't exist in the project it will be created automatically. If initiated from server side SDKs, new member will automatically be added to the team.
+Invite a new member to join your team. If initiated from the client SDK, an email with a link to join the team will be sent to the member's email address and an account will be created for them should they not be signed up already. If initiated from server-side SDKs, the new member will automatically be added to the team.
 
-Use the 'URL' parameter to redirect the user from the invitation email back to your app. When the user is redirected, use the [Update Team Membership Status](/docs/client/teams#teamsUpdateMembershipStatus) endpoint to allow the user to accept the invitation to the team.  While calling from side SDKs the redirect url can be empty string.
+Use the 'url' parameter to redirect the user from the invitation email back to your app. When the user is redirected, use the [Update Team Membership Status](/docs/client/teams#teamsUpdateMembershipStatus) endpoint to allow the user to accept the invitation to the team. 
 
-Please note that in order to avoid a [Redirect Attacks](https://github.com/OWASP/CheatSheetSeries/blob/master/cheatsheets/Unvalidated_Redirects_and_Forwards_Cheat_Sheet.md) the only valid redirect URL's are the once from domains you have set when added your platforms in the console interface.
+Please note that to avoid a [Redirect Attack](https://github.com/OWASP/CheatSheetSeries/blob/master/cheatsheets/Unvalidated_Redirects_and_Forwards_Cheat_Sheet.md) the only valid redirect URL's are the once from domains you have set when adding your platforms in the console interface.

docs/references/teams/create-team.md

@@ -1 +1 @@
-Create a new team. The user who creates the team will automatically be assigned as the owner of the team. The team owner can invite new members, who will be able add new owners and update or delete the team from your project.
+Create a new team. The user who creates the team will automatically be assigned as the owner of the team. Only the users with the owner role can invite new members, add new owners and delete or update the team.

docs/references/teams/delete-team.md

@@ -1 +1 @@
-Delete a team by its unique ID. Only team owners have write access for this resource.
+Delete a team using its ID. Only team members with the owner role can delete the team.

docs/references/teams/get-team-members.md

@@ -1 +1 @@
-Get a team members by the team unique ID. All team members have read access for this list of resources.
+Use this endpoint to list a team's members using the team's ID. All team members have read access to this endpoint.

docs/references/teams/get-team.md

@@ -1 +1 @@
-Get a team by its unique ID. All team members have read access for this resource.
+Get a team by its ID. All team members have read access for this resource.

docs/references/teams/list-teams.md

@@ -1 +1,3 @@
-Get a list of all the current user teams. You can use the query params to filter your results. On admin mode, this endpoint will return a list of all of the project's teams. [Learn more about different API modes](/docs/admin).
+Get a list of all the teams in which the current user is a member. You can use the parameters to filter your results.
+
+In admin mode, this endpoint returns a list of all the teams in the current project. [Learn more about different API modes](/docs/admin).

docs/references/teams/update-team-membership-roles.md

@@ -0,0 +1 @@
+Modify the roles of a team member. Only team members with the owner role have access to this endpoint. Learn more about [roles and permissions](/docs/permissions).

docs/references/teams/update-team.md

@@ -1 +1 @@
-Update a team by its unique ID. Only team owners have write access for this resource.
+Update a team using its ID. Only members with the owner role can update the team.