From 4851f51d8bdb95d8476a5dada955026123a26a5d Mon Sep 17 00:00:00 2001
From: Tom Moor <tom.moor@gmail.com>
Date: Mon, 16 Mar 2020 08:30:15 -0700
Subject: [PATCH] docs: Add documentation for groups API endpoints (#1211)

* docs: Add documentation for groups API endpoints
fix: Remove useless permission query param

* restore permission filter on collections.group_memberships

* tweak language
---
 server/api/groups.js           |  17 +---
 server/pages/developers/Api.js | 164 ++++++++++++++++++++++++++++++---
 2 files changed, 155 insertions(+), 26 deletions(-)

diff --git a/server/api/groups.js b/server/api/groups.js
index a64e2141b..82944a6b2 100644
--- a/server/api/groups.js
+++ b/server/api/groups.js
@@ -148,20 +148,14 @@ router.post('groups.delete', auth(), async ctx => {
 });
 
 router.post('groups.memberships', auth(), pagination(), async ctx => {
-  const { id, query, permission } = ctx.body;
+  const { id, query } = ctx.body;
   ctx.assertUuid(id, 'id is required');
 
   const user = ctx.state.user;
   const group = await Group.findByPk(id);
-
   authorize(user, 'read', group);
 
-  let where = {
-    groupId: id,
-  };
-
   let userWhere;
-
   if (query) {
     userWhere = {
       name: {
@@ -170,15 +164,8 @@ router.post('groups.memberships', auth(), pagination(), async ctx => {
     };
   }
 
-  if (permission) {
-    where = {
-      ...where,
-      permission,
-    };
-  }
-
   const memberships = await GroupUser.findAll({
-    where,
+    where: { groupId: id },
     order: [['createdAt', 'DESC']],
     offset: ctx.state.pagination.offset,
     limit: ctx.state.pagination.limit,
diff --git a/server/pages/developers/Api.js b/server/pages/developers/Api.js
index 1cb463652..a75fcfd0c 100644
--- a/server/pages/developers/Api.js
+++ b/server/pages/developers/Api.js
@@ -45,7 +45,7 @@ export default function Api() {
               the token.
             </Description>
             <Arguments>
-              <Argument id="id" description="Collection id" required />
+              <Argument id="id" description="Collection ID" required />
             </Arguments>
           </Method>
 
@@ -74,7 +74,7 @@ export default function Api() {
               />
               <Argument
                 id="documentId"
-                description="UUID of the associated document"
+                description="ID of the associated document"
               />
             </Arguments>
           </Method>
@@ -144,7 +144,7 @@ export default function Api() {
               Returns detailed information on a document collection.
             </Description>
             <Arguments>
-              <Argument id="id" description="Collection id" required />
+              <Argument id="id" description="Collection ID" required />
             </Arguments>
           </Method>
 
@@ -169,7 +169,7 @@ export default function Api() {
               folders inside the zip file.
             </Description>
             <Arguments>
-              <Argument id="id" description="Collection id" required />
+              <Argument id="id" description="Collection ID" required />
             </Arguments>
           </Method>
 
@@ -232,14 +232,49 @@ export default function Api() {
             </Arguments>
           </Method>
 
+          <Method
+            method="collections.add_group"
+            label="Add a group to a collection"
+          >
+            <Description>
+              This method allows you to give all members in a group access to a
+              collection.
+            </Description>
+            <Arguments>
+              <Argument id="id" description="Collection ID" required />
+              <Argument
+                id="groupId"
+                description="Group ID to add to the collection"
+              />
+            </Arguments>
+          </Method>
+
+          <Method
+            method="collections.remove_group"
+            label="Remove a group from a collection"
+          >
+            <Description>
+              This method allows you to revoke all members in a group access to
+              a collection. Note that members of the group may still retain
+              access through other groups or individual memberships.
+            </Description>
+            <Arguments>
+              <Argument id="id" description="Collection ID" required />
+              <Argument
+                id="groupId"
+                description="Group ID to remove from the collection"
+              />
+            </Arguments>
+          </Method>
+
           <Method
             method="collections.memberships"
             label="List collection members"
           >
             <Description>
-              This method allows you to list a collections memberships. This is
-              both a collections maintainers, and user permissions for read and
-              write if the collection is private
+              This method allows you to list a collections individual
+              memberships. This is both a collections maintainers, and user
+              permissions for read and write if the collection is private
             </Description>
             <Arguments pagination>
               <Argument id="id" description="Collection ID" required />
@@ -251,6 +286,25 @@ export default function Api() {
             </Arguments>
           </Method>
 
+          <Method
+            method="collections.group_memberships"
+            label="List collection group members"
+          >
+            <Description>
+              This method allows you to list a collections group memberships.
+              This is the list of groups that have been given access to the
+              collection.
+            </Description>
+            <Arguments pagination>
+              <Argument id="id" description="Collection ID" required />
+              <Argument id="query" description="Filter results by group name" />
+              <Argument
+                id="permission"
+                description="Filter results by permission"
+              />
+            </Arguments>
+          </Method>
+
           <Method method="collections.delete" label="Delete a collection">
             <Description>
               Delete a collection and all of its documents. This action can’t be
@@ -629,6 +683,97 @@ export default function Api() {
             </Arguments>
           </Method>
 
+          <Method method="groups.create" label="Create a group">
+            <Description>
+              This method allows you to create a new group to organize people in
+              the team.
+            </Description>
+            <Arguments pagination>
+              <Argument
+                id="name"
+                description="The name of the group"
+                required
+              />
+            </Arguments>
+          </Method>
+
+          <Method method="groups.update" label="Update a group">
+            <Description>
+              This method allows you to update an existing group. At this time
+              the only field that can be edited is the name.
+            </Description>
+            <Arguments pagination>
+              <Argument id="id" description="Group ID" required />
+              <Argument
+                id="name"
+                description="The name of the group"
+                required
+              />
+            </Arguments>
+          </Method>
+
+          <Method method="groups.delete" label="Delete a group">
+            <Description>
+              Deleting a group will cause all of its members to lose access to
+              any collections the group has been given access to. This action
+              can’t be undone so please be careful.
+            </Description>
+            <Arguments>
+              <Argument id="id" description="Group ID" required />
+            </Arguments>
+          </Method>
+
+          <Method method="groups.info" label="Get a group">
+            <Description>Returns detailed information on a group.</Description>
+            <Arguments>
+              <Argument id="id" description="Group ID" required />
+            </Arguments>
+          </Method>
+
+          <Method method="groups.list" label="List groups">
+            <Description>
+              List all groups the current user has access to.
+            </Description>
+            <Arguments pagination />
+          </Method>
+
+          <Method
+            method="groups.memberships"
+            label="List the group memberships"
+          >
+            <Description>
+              List members in a group, the query parameter allows filtering by
+              user name.
+            </Description>
+            <Arguments pagination>
+              <Argument id="id" description="Group ID" />
+              <Argument id="query" description="Search query" />
+            </Arguments>
+          </Method>
+
+          <Method method="groups.add_user" label="Add a group member">
+            <Description>
+              This method allows you to add a user to a group.
+            </Description>
+            <Arguments>
+              <Argument id="id" description="Group ID" required />
+              <Argument id="userId" description="User ID to add to the group" />
+            </Arguments>
+          </Method>
+
+          <Method method="groups.remove_user" label="Remove a group member">
+            <Description>
+              This method allows you to remove a user from a group.
+            </Description>
+            <Arguments>
+              <Argument id="id" description="Group ID" required />
+              <Argument
+                id="userId"
+                description="User ID to remove from the group"
+              />
+            </Arguments>
+          </Method>
+
           <Method method="shares.list" label="List shared document links">
             <Description>
               List all your currently shared document links.
@@ -783,10 +928,7 @@ const Arguments = (props: ArgumentsProps) => (
     </thead>
     <tbody>
       <Argument id="token" description="Authentication token" required />
-      {props.pagination && (
-        // $FlowIssue
-        <PaginationArguments />
-      )}
+      {props.pagination && <PaginationArguments />}
       {props.children}
     </tbody>
   </Table>