Working example of API file metadata update on STATA file?

[kuhlaid]

What steps does it take to reproduce the issue?
I am trying to recreate https://guides.dataverse.org/en/5.13/api/native-api.html#updating-file-metadata on some STATA file metadata I have but I have tried just about everything with no luck. I requested the existing file metadata using https://demo.dataverse.org/api/files/:persistentId/metadata?persistentId=doi:10.70122/FK2/YUUS5M/77CV8Z with no problem.

When I try to update the metadata with additional information using the following terminal commands...

export API_TOKEN=xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx
export SERVER_URL=https://demo.dataverse.org/api/files/:persistentId/metadata?persistentId=doi:10.70122/FK2/YUUS5M/77CV8Z

curl -H "X-Dataverse-key:$API_TOKEN" -X POST \
  -F 'jsonData={"label": "F1_SUBJECT.tab", "directoryLabel": "data/reference", "description": "This is the first file generated for this dataset and contains the participant/subject reference IDs, basic subject demographics, PA knee KL grades and reported pain in knees.", "restricted": false, "id": 1869963, "strFileName": "F1_SUBJECT"}' \
  $SERVER_URL

...I receive the following error:

{"status":"ERROR","message":"Filename already exists at data/reference/F1_SUBJECT.tab"}

This error message seems a bit odd considering I am not trying to replace an existing file, but only the metadata. What am I missing?

[kuhlaid]

I had read the comment by @kmika11 from #8542 about the API call completing if executed on a file in draft state. If I run the CURL command on the data file that currently has a draft version, the API returns a message saying File Metadata update has been completed: {"label":"F1_SUBJECT.tab","directoryLabel":"data/reference","description":"This is the first file generated for this dataset and contains the participant/subject reference IDs, basic subject demographics, PA knee KL grades and reported pain in knees.","restricted":false,"id":1870004} however it does not add the "strFileName": "F1_SUBJECT" metadata that I included in the request.

My first thought is that the API is confusing in that you are not specifying if the update is to occur on the draft or published version of the file. The file is in the draft state when I make the API update request, yet in the API call you are not allowed to specify the draft version. This makes the API request extremely confusing.

Secondly, with the file still in draft mode, I added a (adding comment to set in draft state) comment to the description metadata field from the UI and saved that, but when I made an API request to retrieve the file metadata, it did not return the new comment to the metadata, which means it is pulling the metadata of the published file. The file metadata API GET request (for example https://demo.dataverse.org/api/files/:persistentId/metadata?persistentId=doi:10.70122/FK2/YUUS5M/77CV8Z) only pulls from the published version of the file. If I try to specify draft mode using https://demo.dataverse.org/api/files/:persistentId/metadata/draft?persistentId=doi:10.70122/FK2/YUUS5M/77CV8Z AND include the API token in the request, I receive an error saying An error occurred getting a draft version, you may not have permission to access unpublished data on this dataset. even though I am an admin on the dataset.

If I run the CURL command:

export SERVER_URL=https://demo.dataverse.org/api/files/:persistentId/metadata?persistentId=doi:10.70122/FK2/YUUS5M/77CV8Z

curl -H "X-Dataverse-key:$API_TOKEN" -X POST \
  -F 'jsonData={"label": "F1_SUBJECT.tab", "provFreeform":"Test prov freeform", "directoryLabel": "data/reference", "description": "(API update request 2) This is the first file generated for this dataset and contains the participant/subject reference IDs, basic subject demographics, PA knee KL grades and reported pain in knees.", "restricted": false, "id": 1869963, "strFileName": "F1_SUBJECT"}' \
  $SERVER_URL

... and then publish the dataset, the description includes the (API update request 2) string when I perform a GET request on the file metadata from the API but the response only includes:

{
  "label": "F1_SUBJECT.tab",
  "directoryLabel": "data/reference",
  "description": "(API update request 2) This is the first file generated for this dataset and contains the participant/subject reference IDs, basic subject demographics, PA knee KL grades and reported pain in knees.",
  "restricted": false,
  "id": 1870004
}

... and is missing "provFreeform":"Test prov freeform" and "strFileName": "F1_SUBJECT" elements I added. The API docs at https://guides.dataverse.org/en/5.13/api/native-api.html#updating-file-metadata uses provFreeform as an example, so the documentation should not include this if it is not supported. The file metadata update API is not very useful in the current state.