Merge pull request #11560 from IQSS/11434-roles-api

New API Endpoint for retrieving user selectable roles

Author: ofahimIQSS

doc/release-notes/11434-api-selectable-roles.md

@@ -0,0 +1 @@
+A new endpoint (`api/roles/userSelectable`) has been implemented, which returns the appropriate roles that the calling user can use as filters when searching within their data.

doc/sphinx-guides/source/api/native-api.rst

@@ -5358,6 +5358,32 @@ The fully expanded example above (without environment variables) looks like this
 
   curl -H "X-Dataverse-key:xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx" -X DELETE "https://demo.dataverse.org/api/roles/:alias?alias=sys1"
 
+Get User Selectable Roles
+~~~~~~~~~~~~~~~~~~~~~~~~~
+
+Returns the appropriate roles that the calling user can use as filters when searching within their data.
+
+This endpoint returns the same set of roles displayed as filters on the MyData UI page. The logic for determining which roles are returned is as follows:
+
+- If the user is a superuser, all available roles are returned.
+
+- If the user is not a superuser, only their assigned roles are returned.
+
+- If the user has no assigned roles, all roles are returned as a fallback.
+
+.. code-block:: bash
+
+  export API_TOKEN=xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx
+  export SERVER_URL=https://demo.dataverse.org
+
+  curl -H "X-Dataverse-key:$API_TOKEN" "$SERVER_URL/api/roles/userSelectable"
+
+The fully expanded example above (without environment variables) looks like this:
+
+.. code-block:: bash
+
+  curl -H "X-Dataverse-key:xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx"  "https://demo.dataverse.org/api/roles/userSelectable"
+
 Explicit Groups
 ---------------
 

src/main/java/edu/harvard/iq/dataverse/RoleAssigneeServiceBean.java

@@ -13,6 +13,7 @@
 import edu.harvard.iq.dataverse.authorization.users.AuthenticatedUser;
 import edu.harvard.iq.dataverse.authorization.users.GuestUser;
 import edu.harvard.iq.dataverse.authorization.users.PrivateUrlUser;
+import edu.harvard.iq.dataverse.authorization.users.User;
 import edu.harvard.iq.dataverse.engine.command.DataverseRequest;
 import edu.harvard.iq.dataverse.mydata.MyDataFilterParams;
 import edu.harvard.iq.dataverse.privateurl.PrivateUrlUtil;
@@ -23,12 +24,13 @@
 import java.util.TreeMap;
 import java.util.logging.Logger;
 import java.util.stream.Collectors;
+
+import edu.harvard.iq.dataverse.util.BundleUtil;
 import jakarta.annotation.PostConstruct;
 import jakarta.ejb.EJB;
 import jakarta.ejb.Stateless;
 import jakarta.inject.Named;
 import jakarta.persistence.EntityManager;
-import jakarta.persistence.NamedNativeQuery;
 import jakarta.persistence.PersistenceContext;
 import org.apache.commons.lang3.StringUtils;
 
@@ -154,10 +156,41 @@ private String getRoleIdListClause(List<Long> roleIdList) {
         return " AND r.role_id IN (" + StringUtils.join(outputList, ",") + ")";
     }
 
+    /**
+     * Retrieves the list of {@link DataverseRole}s selectable for the given {@link DataverseRequest}.
+     * <p>
+     * - If the user is a superuser, all roles are returned.<br>
+     * - If the user is not a superuser, their assigned roles are returned. If none are assigned,
+     *   all roles are returned as a fallback.
+     * <p>
+     * This method is based on the logic from {@code MyDataPage.getRolesUsedToCreateCheckboxes}.
+     * It has been implemented in this service to make the logic reusable from parts of the application
+     * other than the JSF UI.
+     *
+     * @param request the dataverse request containing user context
+     * @return a list of relevant {@link DataverseRole}s for the user
+     * @throws NullPointerException if the request is null
+     */
+    public List<DataverseRole> getSelectableDataverseRolesFor(DataverseRequest request) {
+        if (request == null) {
+            throw new NullPointerException(BundleUtil.getStringFromBundle("roleAssigneeServiceBean.error.dataverseRequestCannotBeNull"));
+        }
+
+        User user = request.getUser();
+
+        if (user.isSuperuser()) {
+            return dataverseRoleService.findAll();
+        }
+
+        List<DataverseRole> assignedRoles = getAssigneeDataverseRoleFor(request);
+
+        return assignedRoles.isEmpty() ? dataverseRoleService.findAll() : assignedRoles;
+    }
+
     public List<DataverseRole> getAssigneeDataverseRoleFor(DataverseRequest dataverseRequest) {
 
         if (dataverseRequest == null){
-            throw new NullPointerException("dataverseRequest cannot be null!");
+            throw new NullPointerException(BundleUtil.getStringFromBundle("roleAssigneeServiceBean.error.dataverseRequestCannotBeNull"));
         }
         AuthenticatedUser au = dataverseRequest.getAuthenticatedUser();
         if (au.getUserIdentifier() == null){
@@ -223,7 +256,7 @@ public List<Object[]> getAssigneeAndRoleIdListFor(MyDataFilterParams filterParam
 
     public List<Long> getRoleIdListForGivenAssigneeDvObject(DataverseRequest dataverseRequest, List<Long> roleIdList, Long defPointId) {
         if (dataverseRequest == null){
-            throw new NullPointerException("dataverseRequest cannot be null!");
+            throw new NullPointerException(BundleUtil.getStringFromBundle("roleAssigneeServiceBean.error.dataverseRequestCannotBeNull"));
         }
         AuthenticatedUser au = dataverseRequest.getAuthenticatedUser();
         if (au.getUserIdentifier() == null){
@@ -292,7 +325,7 @@ private String getGroupIdentifierClause(String roleAssigneeIdentifier, List<Stri
 
     public List<Object[]> getRoleIdsFor(DataverseRequest dataverseRequest, List<Long> dvObjectIdList) {
         if (dataverseRequest == null){
-            throw new NullPointerException("dataverseRequest cannot be null!");
+            throw new NullPointerException(BundleUtil.getStringFromBundle("roleAssigneeServiceBean.error.dataverseRequestCannotBeNull"));
         }
         AuthenticatedUser au = dataverseRequest.getAuthenticatedUser();
         if (au.getUserIdentifier() == null){

src/main/java/edu/harvard/iq/dataverse/api/Roles.java

@@ -66,5 +66,11 @@ public Response createNewRole(@Context ContainerRequestContext crc,
                                   new CreateRoleCommand(roleDto.asRole(),
                                                         req,findDataverseOrDie(dvoIdtf))))), getRequestUser(crc));
 	}
-    
+
+    @GET
+    @AuthRequired
+    @Path("userSelectable")
+    public Response getUserSelectableRoles(@Context ContainerRequestContext crc) {
+        return response(req -> ok(jsonDataverseRoles(roleAssigneeSvc.getSelectableDataverseRolesFor(req))), getRequestUser(crc));
+    }
 }

src/main/java/edu/harvard/iq/dataverse/util/json/JsonPrinter.java

@@ -221,6 +221,14 @@ public static <E extends Enum> JsonArrayBuilder enumsToJson(Collection<E> collec
         return arr;
     }
 
+    public static JsonArrayBuilder jsonDataverseRoles(List<DataverseRole> roles) {
+        JsonArrayBuilder jsonArrayOfDataverseRoles = Json.createArrayBuilder();
+        for (DataverseRole role : roles) {
+            jsonArrayOfDataverseRoles.add(json(role));
+        }
+        return jsonArrayOfDataverseRoles;
+    }
+
     public static JsonObjectBuilder json(DataverseRole role) {
         JsonObjectBuilder bld = jsonObjectBuilder()
                 .add("alias", role.getAlias())

src/main/java/propertyFiles/Bundle.properties

@@ -3206,3 +3206,6 @@ updateDatasetFieldsCommand.api.processDatasetUpdate.parseError=Error parsing dat
 
 #AbstractApiBean.java
 abstractApiBean.error.datasetInternalVersionNumberIsOutdated=Dataset internal version number {0} is outdated
+
+#RoleAssigneeServiceBean.java
+roleAssigneeServiceBean.error.dataverseRequestCannotBeNull=DataverseRequest cannot be null.

src/test/java/edu/harvard/iq/dataverse/api/RolesIT.java

@@ -1,15 +1,17 @@
 
 package edu.harvard.iq.dataverse.api;
 
+import edu.harvard.iq.dataverse.authorization.DataverseRole;
 import io.restassured.RestAssured;
 import io.restassured.path.json.JsonPath;
 import io.restassured.response.Response;
-import static jakarta.ws.rs.core.Response.Status.FORBIDDEN;
+
 import java.util.logging.Logger;
+
+import static jakarta.ws.rs.core.Response.Status.*;
 import static org.hamcrest.CoreMatchers.equalTo;
 import static org.junit.jupiter.api.Assertions.assertEquals;
 
-import org.junit.jupiter.api.Assertions;
 import org.junit.jupiter.api.BeforeAll;
 import org.junit.jupiter.api.Test;
 
@@ -108,5 +110,55 @@ public void testCreateDeleteRoles() {
         assertEquals("OK", status);
 
     }
-    
+
+    @Test
+    public void testGetUserSelectableRoles() {
+        Response createAdminUser = UtilIT.createRandomUser();
+
+        String adminUsername = UtilIT.getUsernameFromResponse(createAdminUser);
+        String adminApiToken = UtilIT.getApiTokenFromResponse(createAdminUser);
+        UtilIT.makeSuperUser(adminUsername);
+
+        Response createUser = UtilIT.createRandomUser();
+
+        String username = UtilIT.getUsernameFromResponse(createUser);
+        String apiToken = UtilIT.getApiTokenFromResponse(createUser);
+
+        // Non-superuser with no assigned roles: return all roles as fallback.
+
+        Response getUserSelectableRolesResponse = UtilIT.getUserSelectableRoles(apiToken);
+
+        getUserSelectableRolesResponse.then().assertThat()
+                .statusCode(OK.getStatusCode())
+                .body("data.size()", equalTo(8));
+
+        // Non-superuser with assigned role: return assigned role.
+
+        Response createDataverseResponse = UtilIT.createRandomDataverse(adminApiToken);
+        createDataverseResponse.then().assertThat()
+                .statusCode(CREATED.getStatusCode());
+
+        String dataverseAlias = UtilIT.getAliasFromResponse(createDataverseResponse);
+
+        Response grantUserAddDataset = UtilIT.grantRoleOnDataverse(dataverseAlias, DataverseRole.DS_CONTRIBUTOR, "@" + username, adminApiToken);
+
+        grantUserAddDataset.then().assertThat()
+                .statusCode(OK.getStatusCode())
+                .body("data.assignee", equalTo("@" + username))
+                .body("data._roleAlias", equalTo("dsContributor"));
+
+        getUserSelectableRolesResponse = UtilIT.getUserSelectableRoles(apiToken);
+        getUserSelectableRolesResponse.then().assertThat()
+                .statusCode(OK.getStatusCode())
+                .body("data.size()", equalTo(1))
+                .body("data[0].alias", equalTo(DataverseRole.DS_CONTRIBUTOR));
+
+        // Superuser: return all roles.
+
+        getUserSelectableRolesResponse = UtilIT.getUserSelectableRoles(adminApiToken);
+
+        getUserSelectableRolesResponse.then().assertThat()
+                .statusCode(OK.getStatusCode())
+                .body("data.size()", equalTo(8));
+    }
 }

src/test/java/edu/harvard/iq/dataverse/api/UtilIT.java

@@ -4815,4 +4815,11 @@ public static Response updateDatasetFilesMetadata(String datasetIdOrPersistentId
         return given().header(API_TOKEN_HTTP_HEADER, apiToken).contentType(ContentType.JSON).body(jsonArray.toString())
                 .post("/api/datasets/" + idInPath + "/files/metadata" + optionalQueryParam);
     }
+
+    static Response getUserSelectableRoles(String apiToken) {
+        return given()
+                .header(API_TOKEN_HTTP_HEADER, apiToken)
+                .contentType("application/json")
+                .get("/api/roles/userSelectable");
+    }
 }