HAL links, parent groups, removing the feature to get indirect relati…

…ons until it's sorted out
DSpace · Sep 26, 2019 · 750a6ec · 750a6ec
1 parent ef8b3e6
commit 750a6ec
Show file tree

Hide file tree

Showing 2 changed files with 92 additions and 57 deletions.
diff --git a/epersongroups.md b/epersongroups.md
@@ -27,33 +27,18 @@
   "permanent": true,
   "type": "group",
   "_links": {
-    "groups": {
+    "subgroups": {
       "href": "https://dspace7.4science.it/dspace-spring-rest/api/eperson/groups/617cf46b-535c-42d5-9d22-327ce2eff6dc/groups"
     },
+    "parentgroups": {
+      "href": "https://dspace7.4science.it/dspace-spring-rest/api/eperson/groups/617cf46b-535c-42d5-9d22-327ce2eff6dc/parentgroups"
+    },
     "epersons": {
       "href": "https://dspace7.4science.it/dspace-spring-rest/api/eperson/groups/617cf46b-535c-42d5-9d22-327ce2eff6dc/epersons"
     },
     "self": {
       "href": "https://dspace7.4science.it/dspace-spring-rest/api/eperson/groups/617cf46b-535c-42d5-9d22-327ce2eff6dc"
     }
-  },
-  "_embedded": {
-    "groups": {
-      "_embedded": {
-        "groups": []
-      },
-      "_links": {
-        "self": {
-          "href": "https://dspace7.4science.it/dspace-spring-rest/api/eperson/groups/617cf46b-535c-42d5-9d22-327ce2eff6dc/groups"
-        }
-      },
-      "page": {
-        "number": 0,
-        "size": 0,
-        "totalPages": 1,
-        "totalElements": 0
-      }
-    }
   }
 }
 ```
@@ -79,19 +64,82 @@ To create a new EPerson Group, perform a post with the JSON below to the eperson
 }
 ```
 
+## Parent Groups of a single parent EPerson Group
+
+### Get Parent Groups of a single parent EPerson Group
+
+**GET /api/eperson/groups/<:uuid>/parentgroups**
+
+Retrieves direct parent groups of the given group.
+Requesting indirect parent groups is not supported
+
+Sample:
+* GET /rest/api/eperson/groups/617cf46b-535c-42d5-9d22-327ce2eff6dc/parentgroups
+
+```json
+{
+    "_embedded": {
+      "groups": [
+        {
+          "id": "3b1de75d-5bf9-4ca3-bf4d-42bc8abd0d42",
+          "uuid": "3b1de75d-5bf9-4ca3-bf4d-42bc8abd0d42",
+          "name": "Parent group",
+          "handle": null,
+          "metadata": {
+              "dc.title": [
+                {
+                  "value": "Parent group",
+                  "language": null,
+                  "authority": "",
+                  "confidence": -1,
+                  "place": 0
+                }
+              ]
+          },
+          "permanent": true,
+          "type": "group",
+          "_links": {
+            "subgroups": {
+              "href": "https://dspace7.4science.it/dspace-spring-rest/api/eperson/groups/3b1de75d-5bf9-4ca3-bf4d-42bc8abd0d42/groups"
+            },
+            "parentgroups": {
+              "href": "https://dspace7.4science.it/dspace-spring-rest/api/eperson/groups/3b1de75d-5bf9-4ca3-bf4d-42bc8abd0d42/parentgroups"
+            },
+            "epersons": {
+              "href": "https://dspace7.4science.it/dspace-spring-rest/api/eperson/groups/3b1de75d-5bf9-4ca3-bf4d-42bc8abd0d42/epersons"
+            },
+            "self": {
+              "href": "https://dspace7.4science.it/dspace-spring-rest/api/eperson/groups/3b1de75d-5bf9-4ca3-bf4d-42bc8abd0d42"
+            }
+          }
+        }
+      ]
+    },
+    "_links": {
+      "self": {
+        "href": "https://dspace7.4science.it/dspace-spring-rest/api/eperson/groups/617cf46b-535c-42d5-9d22-327ce2eff6dc/groups"
+      }
+    },
+    "page": {
+      "number": 0,
+      "size": 10,
+      "totalPages": 1,
+      "totalElements": 10
+    }
+}
+```
+
 ## Sub Groups in a single parent EPerson Group
 
 ### Get Sub Groups in a single parent EPerson Group
 
-**GET /api/eperson/groups/<:uuid>/groups**
-
-Filter using parameter:
-* all : retrieve indirect groups as well
+**GET /api/eperson/groups/<:uuid>/subgroups**
 
-Samples:
-* GET /rest/api/eperson/groups/3b1de75d-5bf9-4ca3-bf4d-42bc8abd0d42/groups
-* GET /rest/api/eperson/groups/3b1de75d-5bf9-4ca3-bf4d-42bc8abd0d42/groups?all=true
+Retrieves direct child groups of the given group.
+Requesting indirect child groups is not supported
 
+Sample:
+* GET /rest/api/eperson/groups/3b1de75d-5bf9-4ca3-bf4d-42bc8abd0d42/subgroups
 
 ```json
 {
@@ -116,40 +164,25 @@ Samples:
           "permanent": true,
           "type": "group",
           "_links": {
-            "groups": {
-              "href": "https://dspace7.4science.it/dspace-spring-rest/api/eperson/groups/617cf46b-535c-42d5-9d22-327ce2eff6dc/groups"
+            "subgroups": {
+              "href": "https://dspace7.4science.it/dspace-spring-rest/api/eperson/groups/617cf46b-535c-42d5-9d22-327ce2eff6dc/subgroups"
+            },
+            "parentgroups": {
+              "href": "https://dspace7.4science.it/dspace-spring-rest/api/eperson/groups/617cf46b-535c-42d5-9d22-327ce2eff6dc/parentgroups"
             },
             "epersons": {
               "href": "https://dspace7.4science.it/dspace-spring-rest/api/eperson/groups/617cf46b-535c-42d5-9d22-327ce2eff6dc/epersons"
             },
             "self": {
               "href": "https://dspace7.4science.it/dspace-spring-rest/api/eperson/groups/617cf46b-535c-42d5-9d22-327ce2eff6dc"
             }
-          },
-          "_embedded": {
-            "groups": {
-              "_embedded": {
-                "groups": []
-              },
-              "_links": {
-                "self": {
-                  "href": "https://dspace7.4science.it/dspace-spring-rest/api/eperson/groups/617cf46b-535c-42d5-9d22-327ce2eff6dc/groups"
-                }
-              },
-              "page": {
-                "number": 0,
-                "size": 0,
-                "totalPages": 1,
-                "totalElements": 0
-              }
-            }
           }
         }
       ]
     },
     "_links": {
       "self": {
-        "href": "https://dspace7.4science.it/dspace-spring-rest/api/eperson/groups/3b1de75d-5bf9-4ca3-bf4d-42bc8abd0d42/groups"
+        "href": "https://dspace7.4science.it/dspace-spring-rest/api/eperson/groups/3b1de75d-5bf9-4ca3-bf4d-42bc8abd0d42/subgroups"
       }
     },
     "page": {
@@ -163,15 +196,15 @@ Samples:
 
 ### Add a Group to a parent Group
 
-**POST /api/eperson/groups/<:parentgroupuuid>/groups**
+**POST /api/eperson/groups/<:parentgroupuuid>/subgroups**
 
 To add a child group to a parent group, perform a POST to the Sub groups of a Group endpoint when logged in as admin.
 
 The actual sub group is part of the body using the uri-list
 
 Example:
 ```bash
-curl -i -X POST "https://dspace7.4science.it/dspace-spring-rest/api/eperson/groups/617cf46b-535c-42d5-9d22-327ce2eff6dc/groups"
+curl -i -X POST "https://dspace7.4science.it/dspace-spring-rest/api/eperson/groups/617cf46b-535c-42d5-9d22-327ce2eff6dc/subgroups"
   -H "Content-Type:text/uri-list"
   -d "https://dspace7.4science.it/dspace-spring-rest/api/eperson/groups/05e3dbb8-332b-4487-a3f9-d78431b6cc02"
 ```
@@ -188,22 +221,22 @@ Return codes:
 
 ### Remove a Group from a parent Group
 
-**GET /api/eperson/groups/<:parent_group_uuid>/groups/<:sub_group_uuid>**
+**GET /api/eperson/groups/<:parent_group_uuid>/subgroups/<:sub_group_uuid>**
 
 _Unsupported._ If you want detailed information about a single group, use the `/api/eperson/groups/<:uuid>` endpoint.
 
-**DELETE /api/eperson/groups/<:parent_group_uuid>/groups**
+**DELETE /api/eperson/groups/<:parent_group_uuid>/subgroups**
 
 _Unsupported._ At this time, we do not support removing all subgroups in a single request. Please use `DELETE /api/core/groups/<:parent_group_uuid>/groups/<:sub_group_uuid>` to remove child groups one by one.
 
-**DELETE /api/eperson/groups/<:parent_group_uuid>/groups/<:sub_group_uuid>**
+**DELETE /api/eperson/groups/<:parent_group_uuid>/subgroups/<:sub_group_uuid>**
 
 A DELETE request will result in removing a subgroup from the parent group
 
 Example:
 ```bash
 curl -i -X DELETE 
-  "https://dspace7.4science.it/dspace-spring-rest/api/eperson/groups/617cf46b-535c-42d5-9d22-327ce2eff6dc/groups/05e3dbb8-332b-4487-a3f9-d78431b6cc02"
+  "https://dspace7.4science.it/dspace-spring-rest/api/eperson/groups/617cf46b-535c-42d5-9d22-327ce2eff6dc/subgroups/05e3dbb8-332b-4487-a3f9-d78431b6cc02"
 ```
 
 The above request would remove the mapping between the parent group with UUID `617cf46b-535c-42d5-9d22-327ce2eff6dc`
@@ -222,12 +255,11 @@ Return codes:
 
 **GET /api/eperson/groups/<:uuid>/epersons**
 
-Filter using parameter:
-* all : retrieve indirect epeople as well
+Retrieves direct child epeople of the given group.
+Requesting indirect child epeople is not supported
 
-Samples:
+Sample:
 * GET /rest/api/eperson/groups/3b1de75d-5bf9-4ca3-bf4d-42bc8abd0d42/epersons
-* GET /rest/api/eperson/groups/3b1de75d-5bf9-4ca3-bf4d-42bc8abd0d42/epersons?all=true
 
 
 ```json

diff --git a/epersons.md b/epersons.md
@@ -187,6 +187,9 @@ It will search in:
 A HAL link to retrieve the eperson groups of an eperson is included.
 This will return a pageable list of the groups this person is a direct member of
 
+> TODO: A solution to retrieve direct and indirect groups of an eperson is also required.
+> This would use GroupService.allMemberGroupsSet() and is used e.g. when viewing an EPerson as an admin
+
 ## Search
 **GET /api/eperson/epersons/search/byMetadata?query=<:name>**