add MyData API to dataverse documentaion

[sirineREKIK]

add MyData API to dataverse documentaion

• closes Document - Make use of MyData API "official" #5042

[pdurbin]

@sirineREKIK thanks for the pull request! Can you please take a look at these errors? https://github.com/IQSS/dataverse/actions/runs/4989177823/jobs/8932750403?pr=9596

Thanks!

(I'm giving this a size 3 because it shouldn't take much effort to review and QA.)

[qqmyers]

Roles are customizable. Standard roles include:

[qqmyers]

Looks good. I think my only minor comment is that roles are customizable (i.e. by https://guides.dataverse.org/en/4.15.1/api/native-api.html#id24) so the values shown as parameters are only examples, not all possible values. It would be nice to have a change before this is merged, but I don't think it should be slowed down for that.

[pdurbin]

I haven't tested this and I'm wondering about the "key" thing but I left a little feedback. Thanks for working on this, @sirineREKIK! ❤️

[pdurbin]

• -H with no header?
• sending -H with the API token is preferred to sending "key" (I just noticed the note about key below.) 🤔
• I'd suggest removing GET since it's the default
• https is preferred over http
• I'd replace http://$SERVER_URL with $SERVER_URL
• I'd put quotes around the URL because of all the & characters. Bash will get confused.

[pdurbin]

Is this true?

[pdurbin]

Can we have a release note snippet as well, please? For now (sorry), please see this issue:

• give contributors guidance on how to write a release note snippet #9264

[sirineREKIK]

Can you check if everything is ok or if we need to do something else please?

[pdurbin]

https://dataverse-guide--9596.org.readthedocs.build/en/9596/api/native-api.html#mydata looks reasonable but I haven't tested it.

@kcondon if you could verify that indeed the API token can only be passes as a query parameter ("key") for this API rather than as header (curl -H ...), I would appreciate it!

[kcondon]

https://dataverse-guide--9596.org.readthedocs.build/en/9596/api/native-api.html#mydata looks reasonable but I haven't tested it.

@kcondon if you could verify that indeed the API token can only be passes as a query parameter ("key") for this API rather than as header (curl -H ...), I would appreciate it!

I am able to access this endpoint when passing the api_token ("key") in the header:

curl -H "X-Dataverse-key:$API_TOKEN" "$SERVER_URL/api/mydata/retrieve?role_ids=$ROLE_IDS&dvobject_types=$DVOBJECT_TYPES&published_states=$PUBLISHED_STATES&per_page=$PER_PAGE"

This should be the preferred method since it is more secure. @sirineREKIK Would you mind updating the document to use the header or is there something we are missing here?

[sirineREKIK]

Hello,
@kcondon
From our side, when doing tests to access the endpoint when passing the api_token ("key") in the header, we got an authentication error, you can see the example below:

curl -H "X-Dataverse-key: xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx" "https://demo.dataverse.org/api/v1/mydata/retrieve?dvobject_types=Dataverse&dvobject_types=Dataset&published_states=Published&role_ids=8&per_page=5" | jq .
{
"success": false,
"error_message": "Requires authentication. Please login."
}

Also it is always the same return for all our installation environements.
I don't know if we are missing something, but as mentioned in the example, the test with the datavarese demo site is in error.

[kcondon]

@sirineREKIK Thank you for that information. I was able to reproduce the problem. I still believe passing the key in the header is the correct syntax since all of my previous testing with endpoints has confirmed this is the correct method. However, I do not yet know what's wrong in this case. Also, please note that this syntax is working on my test server.

[kcondon]

@sirineREKIK Ok, I have found the problem but don't know why yet. Release v5.13 appears to fail when passing the key in the header for this endpoint but works for others. in v5.14, due out soon, it works passing it in the header. So, I think we should therefore go with the header form. I'm checking here to see what's changed in the code that might have affected this endpoint. I know there was a roles change but thought it was about creating new roles and inheritance.

[kcondon]

@sirineREKIK It's been confirmed that due to other work in this area, the header behavior was fixed in v5.14. So, let's go with the key in the header format. Thanks! Regards, Kevin

[sirineREKIK]

@kcondon Thank you for that information. Changes are taken into account.
Regards, Sirine.

[kcondon]

@sirineREKIK Thanks, it looks great!

[pdurbin]

I'm glad the header works! Probably due to recent auth refactoring? 🤔

• 9293 - New filter-based design for the API authentication mechanisms (1/2) #9303

Not sure. 😄

[kcondon]

@pdurbin Yes. Guillermo fixed it. I believe this unpublished api implementation predated our move to using the header as a more secure way of passing info. So, really was just never implemented, I think?