API Guide says three endpoints want version ID but giving version ID doesn't work, giving version number does

[jggautier]

Tested on Dataverse 4.19.1, the API Guide documents three endpoints for (1) listing files in a dataset (2) listing metadata blocks for a dataset, and (3) listing a single metadata block for a dataset. The docs indicate that all three endpoints require that a version ID (the database ID of the dataset version) be included:

But the endpoint seems to work only when given the version number, not the version ID.

For example, for this dataset:

• datasetID is 3610475
• version ID is 176718 for version 1
• version ID is 176765 for version 3.1

If you want to use the "list files" endpoint, https://dataverse.harvard.edu/api/datasets/3610475/versions/176718/files doesn't work, but https://dataverse.harvard.edu/api/datasets/3610475/versions/1/files does.

To see if any other endpoints ask for $versionId, I did a control find on the Search, Data Access, Metrics, and SWORD API pages, but only found the three endpoints already mentioned.

[jggautier]

Should the docs be changed to say that the endpoints want the $versionNumber number instead?

E.g. GET http://$SERVER/api/datasets/$id/versions/$versionNumber/files?key=$apiKey

[pdurbin]

@jggautier interesting. So it wants "1". You're making me wonder if "1.0" or "1.1" works.

[jggautier]

Just checked. :) Both work:
https://dataverse.harvard.edu/api/datasets/3610475/versions/1/files
https://dataverse.harvard.edu/api/datasets/3610475/versions/1.0/files

[pdurbin]

@jggautier great! Thanks for checking. Yes, we should document this properly. 😄

[pdurbin]

This issue was reported against Dataverse 4.19 but I believe it was fixed in Dataverse 4.20 in pull request #6600.

Here's how the section in question looks now (as of Dataverse 5.3):

Note that instead of $versionId (which is confusing) the examples now have $VERSION=1.0 to (in my mind) clearly indicate that we are talking about user-facing version numbers like 1.0, 1.1, etc.

I'm going to put this in code review. If there's more that should be done, I'm happy to hack away on it.

[djbrooke]

Thanks @pdurbin !

@jggautier what do you think?

[jggautier]

Thanks! I think this makes the documentation clearer :)