improve the linked dataverse listing API

[pkiraly]

What this PR does / why we need it:

This PR makes the response of the linked dataverse listing API more structured. Instead of returning a formatted string, it returns a structured JSON, where the individual data pieces are separated.

Which issue(s) this PR closes:

Closes #9650

Special notes for your reviewer:

Right now the API can be executed only by administrator. I think it might be changed so that the owner of the dataset is also able to execute it.

Suggestions on how to test this:

1. build and deploy the war file
2. create a link in a dataset
3. use API to retrieve the list of linked dataverses via curl -s -H "X-Dataverse-key:$API_TOKEN" $SERVER_URL/api/datasets/$DATASET_ID/links

it will returns something like this:

{
  "status": "OK",
  "data": {
    "id": 5,
    "identifier": "FK2/OTCWMM",
    "linked-dataverses": [
      {
        "id": 2,
        "alias": "dataverse1",
        "displayName": "Lab experiments 2023 June"
      }
    ]
  }
}

Does this PR introduce a user interface change? If mockups are available, please link/include them here:

No

Is there a release notes update needed for this change?:

It might be worth to mention about this API, which previously was not documented.

Additional documentation:

There were a previous PR about the documentation of the API.

[coveralls]

coverage: 20.869% (-0.001%) from 20.87%
when pulling 18db193 on pkiraly:9650-5-improve-list-linked-dataverses-API
into 08249f5 on IQSS:develop.

[pdurbin]

I like the structure! However, what about backward compatibility? 🤔

[pdurbin]

Should we keep this line in for backward compatibility?

[pkiraly]

OK, I'll put it back.

[pkiraly]

@pdurbin Sorry, do you mean the key of the object ("dataverses that link to dataset id X") or the value (e.g. "crc990 (id 18802)")?

[pdurbin]

Well, I think you need both for backward compatibility. We'd want dataversesThatLinkToThisDatasetIdBuilder to have whatever value it has always had.

[stevenwinship]

It was decided today that there is no need for backward compatibility since the api was never documented

[pdurbin]

@pkiraly can you please add a release note snippet?

You can put it here:

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

[pkiraly]

@pdurbin done

[scolapasta]

If you are still interested in this PR, can you please merge and resolve any merge conflicts with the latest from develop? If so, we can prioritize reviewing and QAing the changes. If we don’t hear from you by May 22, 2024, we’ll go ahead and close this PR (it can always be reopened after that date, if there is still interest).

[pkiraly]

I will do it.

[pdurbin]

This is a nice, small API improvement that I think is a good candidate for 6.4.

[pdurbin]

Please update the API changelog.

[pdurbin]

"It was decided today that there is no need for backward compatibility since the api was never documented"

Yes, we rarely document the output JSON, but clients can still rely on it.

Since the change is backward-incompatible, please update the API changelog ( https://guides.dataverse.org/en/latest/api/changelog.html ).

[stevenwinship]

added

[pdurbin]

Thanks! Looks great.

[pdurbin]

I didn't run the code but tests are passing and it looks good to me. Approved.

[ofahimIQSS]

Testing complete in internal.
Made sure non super users can't use this API (test passed).
Tested to ensure that when there is no linked data set, api call does not display data under linked database section.
Test where I linked the dataset to 3 collections: