Clarify role_ids and published_states in API docs#12236
Merged
pdurbin merged 4 commits intoIQSS:developfrom Mar 30, 2026
Merged
Clarify role_ids and published_states in API docs#12236pdurbin merged 4 commits intoIQSS:developfrom
pdurbin merged 4 commits intoIQSS:developfrom
Conversation
Updated API documentation to clarify usage of role_ids and published_states parameters.
scolapasta
moved this from Ready for Triage
to Ready for Review ⏩
in IQSS Dataverse Project
| 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" | ||
|
|
||
| curl -H "X-Dataverse-key:$API_TOKEN" "$SERVER_URL/api/mydata/retrieve?role_ids=6&role_ids=34&dvobject_types=Dataset&published_states=Published&published_states=Draft&published_states=In+Review&selected_page=1" | ||
| Parameters: |
Contributor
There was a problem hiding this comment.
Please fix the indent
Member
There was a problem hiding this comment.
@Parthsuii heads up that I also made some other changes while I was in there. Happy to discuss! 😅
stevenwinship
moved this from Ready for Review ⏩
to In Review 🔎
in IQSS Dataverse Project
pdurbin
reviewed
Mar 27, 2026
| export ROLE_IDS=6 | ||
| export ROLE_ID1=6 | ||
| export ROLE_ID2=8 | ||
| export DVOBJECT_TYPES=Dataset |
Member
There was a problem hiding this comment.
It looks like dvobject_types can be repeated as well...
@QueryParam("dvobject_types") List<DvObject.DType> dvobject_types,
@QueryParam("published_states") List<String> published_states,
@QueryParam("metadata_fields") List<String> metadataFields,
@QueryParam("selected_page") Integer selectedPage,
@QueryParam("mydata_search_term") String searchTerm,
@QueryParam("role_ids") List<Long> roleIds,
... so let's add that to the example.
pdurbin
reviewed
Mar 27, 2026
| ``dvobject_types`` Type of object, several possible values among: ``DataFile`` , ``Dataset`` & ``Dataverse`` . | ||
|
|
||
| ``published_states`` State of the object, several possible values among:``Published`` , ``Unpublished`` , ``Draft`` , ``Deaccessioned`` & ``In+Review`` . | ||
| ``published_states`` State of the object. Multiple "published_states" parameters can be used. Several possible values among: ``Published`` , ``Unpublished`` , ``Draft`` , ``Deaccessioned`` & ``In+Review`` |
Member
There was a problem hiding this comment.
This might look better as a bulleted list like we've done with the list of role ids above.
Updated environment variable names and improved formatting for clarity in the curl example.
pdurbin
approved these changes
Mar 30, 2026
Member
pdurbin
left a comment
pdurbin
left a comment
There was a problem hiding this comment.
Looks good, merging. Thanks, @Parthsuii!
github-project-automation
bot
moved this from In Review 🔎
to Ready for QA ⏩
in IQSS Dataverse Project
github-project-automation
bot
moved this from Ready for QA ⏩
to Merged 🚀
in IQSS Dataverse Project
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
5 participants
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
What this PR does / why we need it:
Updates the MyData API documentation to clarify that role_ids and published_states parameters can be used multiple times in a single query (e.g., &role_ids=1&role_ids=6).
Which issue(s) this PR closes:
Special notes for your reviewer:
I updated the curl example and added "Multiple parameters can be used" to the relevant parameter descriptions to match the existing documentation style for fq.
Suggestions on how to test this:
View the updated MyData section in the API Guide to ensure the examples and parameter notes are clear and correctly formatted.
Does this PR introduce a user interface change?:
No.
Is there a release notes update needed for this change?:
Yes: Clarified documentation for filtering by multiple roles and states in MyData API.
Additional documentation:
N/A
Preview at https://dataverse-guide--12236.org.readthedocs.build/en/12236/api/native-api.html#mydata