Merge pull request #11669 from IQSS/11633-list-dataverse-links-api-change

refactor json response for get dataverse links api

Author: ofahimIQSS

doc/release-notes/11633-list-dataverse-links-api-change.md

@@ -0,0 +1 @@
+The [API for listing the collections a dataverse has been linked to](https://guides.dataverse.org/en/latest/admin/dataverses-datasets.html#list-dataverse-collection-links) (`api/dataverses/$dataverse-alias/links`) has been refactored to return a new Json format. This is a breaking API.

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

@@ -9,8 +9,10 @@ This API changelog is experimental and we would love feedback on its usefulness.
 
 v6.8
 ----
+
 - For POST /api/files/{id}/metadata passing an empty string ("description":"")  or array ("categories":[]) will no longer be ignored. Empty fields will now clear out the values in the file's metadata. To ignore the fields simply do not include them in the JSON string.
 - For PUT /api/datasets/{id}/editMetadata the query parameter "sourceInternalVersionNumber" has been removed and replaced with "sourceLastUpdateTime" to verify that the data being edited hasn't been modified and isn't stale.
+- For GET /api/dataverses/$dataverse-alias/links the Json response has changed breaking the backward compatibility of the API.
 
 v6.7
 ----

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

@@ -34,10 +34,7 @@
 import static edu.harvard.iq.dataverse.util.StringUtil.nonEmpty;
 import static edu.harvard.iq.dataverse.util.json.JsonPrinter.*;
 
-import edu.harvard.iq.dataverse.util.json.JSONLDUtil;
-import edu.harvard.iq.dataverse.util.json.JsonParseException;
-import edu.harvard.iq.dataverse.util.json.JsonPrinter;
-import edu.harvard.iq.dataverse.util.json.JsonUtil;
+import edu.harvard.iq.dataverse.util.json.*;
 
 import java.io.*;
 import java.util.*;
@@ -1707,13 +1704,16 @@ public Response listLinks(@Context ContainerRequestContext crc, @PathParam("iden
             List<Dataset> datasetsThisDvHasLinkedToList = dataverseSvc.findDatasetsThisIdHasLinkedTo(dv.getId());
             JsonArrayBuilder datasetsThisDvHasLinkedToBuilder = Json.createArrayBuilder();
             for (Dataset dataset : datasetsThisDvHasLinkedToList) {
-                datasetsThisDvHasLinkedToBuilder.add(dataset.getLatestVersion().getTitle());
+                JsonObjectBuilder ds = new NullSafeJsonBuilder();
+                ds.add("title", dataset.getLatestVersion().getTitle());
+                ds.add("identifier",  dataset.getProtocol() + ":" + dataset.getAuthority() + "/" + dataset.getIdentifier());
+                datasetsThisDvHasLinkedToBuilder.add(ds);
             }
 
             JsonObjectBuilder response = Json.createObjectBuilder();
-            response.add("dataverses that the " + dv.getAlias() + " dataverse has linked to", dvsThisDvHasLinkedToBuilder);
-            response.add("dataverses that link to the " + dv.getAlias(), dvsThatLinkToThisDvBuilder);
-            response.add("datasets that the " + dv.getAlias() + " has linked to", datasetsThisDvHasLinkedToBuilder);
+            response.add("linkedDataverses", dvsThisDvHasLinkedToBuilder);
+            response.add("dataversesLinkingToThis", dvsThatLinkToThisDvBuilder);
+            response.add("linkedDatasets", datasetsThisDvHasLinkedToBuilder);
             return ok(response);
 
         } catch (WrappedResponse wr) {

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

@@ -10,6 +10,7 @@
 import java.util.logging.Logger;
 
 import static jakarta.ws.rs.core.Response.Status.*;
+import static org.hamcrest.CoreMatchers.containsString;
 import static org.hamcrest.CoreMatchers.equalTo;
 import static org.junit.jupiter.api.Assertions.*;
 
@@ -80,6 +81,13 @@ public void testLinkedDataset() {
         tryToLinkUnpublishedDataset.then().assertThat()
                 .statusCode(OK.getStatusCode());
 
+        Response getLinksResponse = UtilIT.getDataverseLinks(dataverse2Alias, superuserApiToken);
+        getLinksResponse.prettyPrint();
+        getLinksResponse.then().assertThat()
+                .statusCode(OK.getStatusCode());
+        assertEquals("Darwin's Finches", JsonPath.from(getLinksResponse.asString()).getString("data.linkedDatasets[0].title"));
+        assertEquals(datasetPid, JsonPath.from(getLinksResponse.asString()).getString("data.linkedDatasets[0].identifier"));
+
         // A dataset cannot be linked to its parent dataverse.
         Response tryToLinkToParentDataverse = UtilIT.linkDataset(datasetPid, dataverse1Alias, superuserApiToken);
         tryToLinkToParentDataverse.prettyPrint();
@@ -126,6 +134,17 @@ public void testCreateDeleteDataverseLink() {
                 .statusCode(FORBIDDEN.getStatusCode())
                 .body("message", equalTo(dataverseAlias + " has already been linked to " + dataverseAlias2 + "."));
 
+        Response getLinksResponse = UtilIT.getDataverseLinks(dataverseAlias, apiToken);
+        getLinksResponse.prettyPrint();
+        getLinksResponse.then().assertThat()
+                .statusCode(OK.getStatusCode())
+                .body("data.dataversesLinkingToThis[0]", equalTo(dataverseAlias2));
+        getLinksResponse = UtilIT.getDataverseLinks(dataverseAlias2, apiToken);
+        getLinksResponse.prettyPrint();
+        getLinksResponse.then().assertThat()
+                .statusCode(OK.getStatusCode())
+                .body("data.linkedDataverses[0]", equalTo(dataverseAlias));
+
         Response deleteLinkingDataverseResponse = UtilIT.deleteDataverseLink(dataverseAlias, dataverseAlias2, apiToken);
         deleteLinkingDataverseResponse.prettyPrint();
         deleteLinkingDataverseResponse.then().assertThat()

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

@@ -2109,6 +2109,13 @@ static Response createDataverseLink(String linkedDataverseAlias, String linkingD
             .put("api/dataverses/" + linkedDataverseAlias + "/link/" + linkingDataverseAlias);
         return response;
     }
+
+    static Response getDataverseLinks(String dataverseAlias, String apiToken) {
+        Response response = given()
+                .header(API_TOKEN_HTTP_HEADER, apiToken)
+                .get("api/dataverses/"+ dataverseAlias + "/links");
+        return response;
+    }
 
     static Response deleteDataverseLink(String linkedDataverseAlias, String linkingDataverseAlias, String apiToken) {
         Response response = given()