Merge pull request #241 from DSpace/search-nonmembers

Contract for `isNotMemberOf` searches for Groups and EPersons

Author: tdonohue

epersongroups.md

@@ -327,14 +327,40 @@ Return codes:
 * 404 Not found - if the parent group doesn't exist
 * 422 Unprocessable Entity - if the child group doesn't exist or if the specified eperson doesn't exist
 
-## Search
-**GET /api/eperson/groups/search/byMetadata?query=<:name>**
+## Search Methods
 
-This supports a basic search in the metadata.
+### byMetadata
+**GET /api/eperson/groups/search/byMetadata?query=<:string>**
+
+This supports a basic search across all Groups via their metadata.
+It will search in:
+* UUID (exact match)
+* group name
+
+It returns the list of GroupRest instances, if any, matching the user query
+
+Return codes:
+* 200 OK - if the operation succeed
+* 400 Bad Request - if the 'query' parameter is missing or invalid
+* 401 Unauthorized - if you are not authenticated
+* 403 Forbidden - if you are not logged in with sufficient permissions. Only system administrators or Community/Collection administrators can use this endpoint.
+
+### isNotMemberOf
+**GET /api/eperson/groups/search/isNotMemberOf?group=<:uuid>&query=<:string>**
+
+This supports a basic search across all Groups which are not already a member (subgroup) of the provided Group (in the 'group' parameter). Therefore it searches across Groups _not already listed_ on the `/api/eperson/groups/<:uuid>/subgroups` endpoint for the provided group.
 It will search in:
 * UUID (exact match)
 * group name
 
+It returns the list of GroupRest instances, if any, matching the user query
+
+Return codes:
+* 200 OK - if the operation succeed
+* 400 Bad Request - if the 'group' or 'query' parameter is missing or invalid
+* 401 Unauthorized - if you are not authenticated
+* 403 Forbidden - if you are not logged in with sufficient permissions. Only system administrators or Community/Collection administrators can use this endpoint.
+
 ## Related DSpace Object of group
 **GET /api/eperson/groups/<:uuid>/object** (READ-ONLY)
 

epersons.md

@@ -60,8 +60,8 @@
 }
 ```
 
-### Search methods
-#### byEmail
+## Search methods
+### byEmail
 **/api/eperson/epersons/search/byEmail?email=<:string>**
 
 The supported parameters are:
@@ -75,10 +75,10 @@ Return codes:
 * 401 Unauthorized - if you are not authenticated
 * 403 Forbidden - if you are not logged in with sufficient permissions. Only system administrators and users with READ rights on the target EPerson can use the endpoint
 
-#### byMetadata
-**GET /api/eperson/epersons/search/byMetadata?query=<:name>**
+### byMetadata
+**GET /api/eperson/epersons/search/byMetadata?query=<:string>**
 
-This supports a basic search in the metadata.
+This supports a basic search across all EPerson accounts via their metadata.
 It will search in:
 * UUID (exact match)
 * first name
@@ -89,9 +89,27 @@ It returns the list of EPersonRest instances, if any, matching the user query
 
 Return codes:
 * 200 OK - if the operation succeed
-* 400 Bad Request - if the email parameter is missing or invalid
+* 400 Bad Request - if the 'query' parameter is missing or invalid
 * 401 Unauthorized - if you are not authenticated
-* 403 Forbidden - if you are not logged in with sufficient permissions. Only system administrators and users with READ rights on the target EPerson can use the endpoint
+* 403 Forbidden - if you are not logged in with sufficient permissions. Only system administrators or Community/Collection administrators can use this endpoint.
+
+### isNotMemberOf
+**GET /api/eperson/epersons/search/isNotMemberOf?group=<:uuid>&query=<:string>**
+
+This supports a basic search across all EPersons which are not already a member of the provided Group (in the 'group' parameter). Therefore it searches EPersons _not already listed_ on the `/api/eperson/groups/<:uuid>/epersons` endpoint for the provided group.
+It will search in:
+* UUID (exact match)
+* first name
+* last name
+* email address
+
+It returns the list of EPersonRest instances, if any, matching the user query
+
+Return codes:
+* 200 OK - if the operation succeed
+* 400 Bad Request - if the 'group' or 'query' parameter is missing or invalid
+* 401 Unauthorized - if you are not authenticated
+* 403 Forbidden - if you are not logged in with sufficient permissions. Only system administrators or Community/Collection administrators can use this endpoint.
 
 ## Patch operations