Update get file endpoint to add a datasetVersion optional query parameter and extend its payload

[MellyGray]

Overview of the Feature Request

Update the Get JSON Representation of a File endpoint to include a datasetVersion optional query parameter. This parameter would allow users to specify the datasetVersion of the file they wish to retrieve, in the same way that happens when using the Get JSON Representation of a Dataset endpoint

Example /api/files/:persistentId/datasetVersion/3.0?persistentId=doi:10.70122/FK2/QJANR3/J2MR4Q

A part from the new datasetVersion query parameter we also want to include the dataset version information in the payload. This will allow the SPA to display the File Page with all the dataset version data that used to appear in the JSF UI.

This is the dataset version information needed in the SPA:

versionId: number
displayName: string
versionNumber: {majorNumber?: number, minorNumber?: number}
publishingStatus: string
citation: string
isLatest: boolean
isInReview: boolean
latestVersionPublishingStatus: string

What kind of user is the feature intended for?
API User

What inspired the request?

This request is inspired by the need to access specific versions of files metadata to display them in the SPA.

This conversation inspired the request:

• 115 - Create use case to get a file dataverse-client-javascript#119 (comment)

What existing behavior do you want changed?

The 'Get JSON Representation of a File' endpoint

Any brand new behavior do you want to add to Dataverse?

Allow API users to specify the dataset version of the file they wish to retrieve.

Modify the get file endpoint to match the structure of the get dataset endpoint

Any open or closed issues related to this feature request?

• Create use case to get a file dataverse-client-javascript#115

[qqmyers]

FWIW: There are two things that can happen with files. The metadata (including filename) can be updated in a new dataset version and a file can be uploaded to replace a file in the previous version.

In the former case, it is the same file id/DOI but the version that is relevant is the dataset version - there isn't really a version number for the file itself. If you just resolve the DOI, I think the current UI shows the file as it exists in the latest published version or, if it isn't in the latest published version, as it was in the first version it was in. (Perhaps odd - but the DOI points to the file page w/o any version info so some default choice has to be made).

In the latter case, it has a separate id and DOI (if file PIDs are on), so nominally no version info is needed to see the right file. (While Dataverse tracks whether one file replaced another, I don't think the current UI lets you see that at all (at least not on the file page). You just see the set of files in a dataset version on the dataset page and can then go the the file that is in that version by using it's id/DOI to get to the right file page.).

If I understand this issue is really only aimed at the first case. For the API, I wonder if it would make more sense to have an optional query parameter, e.g. ?datasetVersion= or ?inVersion= to make it clearer that it is not a file version (and that there may not be a /versions/1.0 of the file if it wasn't in dataset version 1.0) - though we do already appear to have /draft as an optional path parameter to get the json for a file in the draft dataset version.

[MellyGray]

Thanks for the explanation!

I think the issue pertains to the first case, where the file metadata is updated between dataset versions.

Let me see if I have understood correctly: It's not possible to have a dataset with version=1.0 that includes a file with version=2.0. The version of the file always refers to the dataset version. So, in the UI, when I'm accessing https://demo.dataverse.org/file.xhtml?fileId=2111563&version=3.1, it actually means https://demo.dataverse.org/file.xhtml?fileId=2111563&datasetVersion=3.1.

Therefore, the correct request for this issue would be to ask for the addition of an optional datasetVersion query parameter to the endpoint

I add @ekraffmiller to the conversation so she's aware of this, since she is reviewing the related js-dataverse PR