improve the linked dataverse listing API

doc/release-notes/9650-5-improve-list-linked-dataverses-API.md

@@ -0,0 +1,5 @@
+The following API have been added:
+
+/api/datasets/{datasetId}/links
+
+It lists the linked dataverses to a dataset. It can be executed only by administrators.

doc/sphinx-guides/source/admin/dataverses-datasets.rst

@@ -129,15 +129,21 @@ Lists the link(s) created between a dataset and a Dataverse collection (see the
 
     curl -H "X-Dataverse-key: $API_TOKEN" http://$SERVER/api/datasets/$linked-dataset-id/links
 
-It returns a list in the following format:
+It returns a list in the following format (new format as of v6.4):
 
 .. code-block:: json
 
   {
     "status": "OK",
     "data": {
-      "dataverses that link to dataset id 56782": [
-        "crc990 (id 18802)"
+      "id": 5,
+      "identifier": "FK2/OTCWMM",
+      "linked-dataverses": [
+        {
+          "id": 2,
+          "alias": "dataverse1",
+          "displayName": "Lab experiments 2023 June"
+        }
       ]
     }
   }

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

@@ -12,7 +12,7 @@ v6.4
 
 - **/api/datasets/$dataset-id/modifyRegistration**: Changed from GET to POST
 - **/api/datasets/modifyRegistrationPIDMetadataAll**: Changed from GET to POST
-
+- **/api/datasets/{identifier}/links**: The GET endpoint returns a list of Dataverses linked to the given Dataset. The format of the response has changes for v6.4 making it backward incompatible.
 
 v6.3
 ----

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

@@ -2077,10 +2077,16 @@ public Response getLinks(@Context ContainerRequestContext crc, @PathParam("id")
             List<Dataverse> dvsThatLinkToThisDatasetId = dataverseSvc.findDataversesThatLinkToThisDatasetId(datasetId);
             JsonArrayBuilder dataversesThatLinkToThisDatasetIdBuilder = Json.createArrayBuilder();
             for (Dataverse dataverse : dvsThatLinkToThisDatasetId) {
-                dataversesThatLinkToThisDatasetIdBuilder.add(dataverse.getAlias() + " (id " + dataverse.getId() + ")");
+                JsonObjectBuilder datasetBuilder = Json.createObjectBuilder();
+                datasetBuilder.add("id", dataverse.getId());
+                datasetBuilder.add("alias", dataverse.getAlias());
+                datasetBuilder.add("displayName", dataverse.getDisplayName());
+                dataversesThatLinkToThisDatasetIdBuilder.add(datasetBuilder.build());
             }
             JsonObjectBuilder response = Json.createObjectBuilder();
-            response.add("dataverses that link to dataset id " + datasetId, dataversesThatLinkToThisDatasetIdBuilder);
+            response.add("id", datasetId);
+            response.add("identifier", dataset.getIdentifier());
+            response.add("linked-dataverses", dataversesThatLinkToThisDatasetIdBuilder);
             return ok(response);
         } catch (WrappedResponse wr) {
             return wr.getResponse();

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

@@ -2963,6 +2963,34 @@ public void testLinkingDatasets() {
         linkDataset.then().assertThat()
                 .statusCode(OK.getStatusCode());
 
+        // Link another to test the list of linked datasets
+        Response createDataverse3 = UtilIT.createRandomDataverse(apiToken);
+        createDataverse3.prettyPrint();
+        createDataverse3.then().assertThat()
+                .statusCode(CREATED.getStatusCode());
+        String dataverse3Alias = UtilIT.getAliasFromResponse(createDataverse3);
+        Integer dataverse3Id = UtilIT.getDatasetIdFromResponse(createDataverse3);
+        linkDataset = UtilIT.linkDataset(datasetPid, dataverse3Alias, superuserApiToken);
+        linkDataset.prettyPrint();
+        linkDataset.then().assertThat()
+                .statusCode(OK.getStatusCode());
+        // get the list in Json format
+        Response linkDatasetsResponse = UtilIT.getDatasetLinks(datasetPid, superuserApiToken);
+        linkDatasetsResponse.prettyPrint();
+        linkDatasetsResponse.then().assertThat()
+                .statusCode(OK.getStatusCode());
+        JsonObject linkDatasets = Json.createReader(new StringReader(linkDatasetsResponse.asString())).readObject();
+        JsonArray lst = linkDatasets.getJsonObject("data").getJsonArray("linked-dataverses");
+        List<Integer> ids = List.of(dataverse2Id, dataverse3Id);
+        List<Integer> uniqueids = new ArrayList<>();
+        assertEquals(ids.size(), lst.size());
+        for (int i = 0; i < lst.size(); i++) {
+            int id = lst.getJsonObject(i).getInt("id");
+            assertTrue(ids.contains(id));
+            assertFalse(uniqueids.contains(id));
+            uniqueids.add(id);
+        }
+
 //Experimental code for trying to trick test into thinking the dataset has been harvested
 /*
 createDataset = UtilIT.createRandomDatasetViaNativeApi(dataverse1Alias, apiToken);

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

@@ -278,8 +278,8 @@ public void testMoveLinkedDataset() {
                 .body("message", equalTo("Use the query parameter forceMove=true to complete the move. This dataset is linked to the new host dataverse or one of its parents. This move would remove the link to this dataset. "));
 
         JsonObject linksBeforeData = Json.createReader(new StringReader(getLinksBefore.asString())).readObject();
-        assertEquals("OK", linksBeforeData.getString("status"));
-        assertEquals(dataverse2Alias + " (id " + dataverse2Id + ")", linksBeforeData.getJsonObject("data").getJsonArray("dataverses that link to dataset id " + datasetId).getString(0));
+        assertEquals(datasetId, linksBeforeData.getJsonObject("data").getInt("id"));
+        assertEquals(dataverse2Id, linksBeforeData.getJsonObject("data").getJsonArray("linked-dataverses").get(0).asJsonObject().getInt("id"));
 
         boolean forceMove = true;
         Response forceMoveLinkedDataset = UtilIT.moveDataset(datasetId.toString(), dataverse2Alias, forceMove, superuserApiToken);
@@ -308,8 +308,7 @@ public void testMoveLinkedDataset() {
 
         JsonObject linksAfterData = Json.createReader(new StringReader(getLinksAfter.asString())).readObject();
         assertEquals("OK", linksAfterData.getString("status"));
-        assertEquals(0, linksAfterData.getJsonObject("data").getJsonArray("dataverses that link to dataset id " + datasetId).size());
-
+        assertEquals(0, linksAfterData.getJsonObject("data").getJsonArray("linked-dataverses").size());
     }
 
     @Test