From a66195d2f6f8431b2234ed0e7e345aaed8caf1ed Mon Sep 17 00:00:00 2001 From: Parth karalkar <125957510+Parthsuii@users.noreply.github.com> Date: Fri, 20 Mar 2026 12:16:12 +0530 Subject: [PATCH 1/4] Clarify role_ids and published_states in API docs Updated API documentation to clarify usage of role_ids and published_states parameters. --- doc/sphinx-guides/source/api/native-api.rst | 9 ++++----- 1 file changed, 4 insertions(+), 5 deletions(-) diff --git a/doc/sphinx-guides/source/api/native-api.rst b/doc/sphinx-guides/source/api/native-api.rst index 808dbeec815..0f9d1903a3f 100644 --- a/doc/sphinx-guides/source/api/native-api.rst +++ b/doc/sphinx-guides/source/api/native-api.rst @@ -8867,11 +8867,10 @@ A curl example listing objects export PUBLISHED_STATES=Unpublished export PER_PAGE=10 - 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: -``role_id`` Roles are customizable. Standard roles include: +``role_id`` Roles are customizable. Multiple "role_ids" parameters can be used to filter by several roles. Standard roles include: - ``1`` = Admin - ``2`` = File Downloader @@ -8884,7 +8883,7 @@ Parameters: ``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`` ``per_page`` Number of results returned per page. @@ -8896,7 +8895,7 @@ Parameters: ``order`` The order in which to sort. Can either be "asc" or "desc". -``fq`` A filter query to filter the list returned. Multiple "fq" parameters can be used. +``fq`` A filter query (Solr syntax) to narrow the list returned. Multiple "fq" parameters can be used. MyData Collection List ~~~~~~~~~~~~~~~~~~~~~~ From 0bb62961045ee3178ebfe6bc043c7ee7a5fc00c1 Mon Sep 17 00:00:00 2001 From: Philip Durbin Date: Fri, 27 Mar 2026 17:06:20 -0400 Subject: [PATCH 2/4] use env vars #12236 --- doc/sphinx-guides/source/api/native-api.rst | 17 +++++++++++++---- 1 file changed, 13 insertions(+), 4 deletions(-) diff --git a/doc/sphinx-guides/source/api/native-api.rst b/doc/sphinx-guides/source/api/native-api.rst index 0f9d1903a3f..12d294740a9 100644 --- a/doc/sphinx-guides/source/api/native-api.rst +++ b/doc/sphinx-guides/source/api/native-api.rst @@ -8862,15 +8862,24 @@ A curl example listing objects export API_TOKEN=xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx export SERVER_URL=https://demo.dataverse.org - export ROLE_IDS=6 + export ROLE_ID1=6 + export ROLE_ID2=8 export DVOBJECT_TYPES=Dataset - export PUBLISHED_STATES=Unpublished + export PUBLISHED_STATE1=Unpublished + export PUBLISHED_STATE2=Published export PER_PAGE=10 - 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" + curl -H "X-Dataverse-key:$API_TOKEN" "$SERVER_URL/api/mydata/retrieve?role_ids=$ROLE_ID1&role_ids=$ROLE_ID2&dvobject_types=$DVOBJECT_TYPES&published_states=$PUBLISHED_STATE1&published_states=$PUBLISHED_STATE2&per_page=$PER_PAGE" + +The fully expanded example above (without environment variables) looks like this: + +.. code-block:: bash + + curl -H "X-Dataverse-key:xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx" https://demo.dataverse.org/api/mydata/retrieve?role_ids=6&role_ids=8&dvobject_types=Dataset&published_states=Unpublished&published_states=Published&per_page=10 + Parameters: -``role_id`` Roles are customizable. Multiple "role_ids" parameters can be used to filter by several roles. Standard roles include: +``role_ids`` Roles are customizable. Multiple "role_ids" parameters can be used to filter by several roles. Standard roles include: - ``1`` = Admin - ``2`` = File Downloader From 29c1266dbcd96e66aac5ec2d414d3b9c7d785c0e Mon Sep 17 00:00:00 2001 From: Parth karalkar <125957510+Parthsuii@users.noreply.github.com> Date: Sat, 28 Mar 2026 20:38:54 +0530 Subject: [PATCH 3/4] Refactor curl example and parameter descriptions Updated environment variable names and improved formatting for clarity in the curl example. --- doc/sphinx-guides/source/api/native-api.rst | 56 +++++++++------------ 1 file changed, 25 insertions(+), 31 deletions(-) diff --git a/doc/sphinx-guides/source/api/native-api.rst b/doc/sphinx-guides/source/api/native-api.rst index 12d294740a9..8005352c5c2 100644 --- a/doc/sphinx-guides/source/api/native-api.rst +++ b/doc/sphinx-guides/source/api/native-api.rst @@ -8860,16 +8860,18 @@ A curl example listing objects .. code-block:: bash - export API_TOKEN=xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx +export API_TOKEN=xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx export SERVER_URL=https://demo.dataverse.org export ROLE_ID1=6 export ROLE_ID2=8 - export DVOBJECT_TYPES=Dataset + export DVTYPE1=Dataset + export DVTYPE2=Dataverse export PUBLISHED_STATE1=Unpublished export PUBLISHED_STATE2=Published export PER_PAGE=10 - curl -H "X-Dataverse-key:$API_TOKEN" "$SERVER_URL/api/mydata/retrieve?role_ids=$ROLE_ID1&role_ids=$ROLE_ID2&dvobject_types=$DVOBJECT_TYPES&published_states=$PUBLISHED_STATE1&published_states=$PUBLISHED_STATE2&per_page=$PER_PAGE" + curl -H "X-Dataverse-key:$API_TOKEN" \ + "$SERVER_URL/api/mydata/retrieve?role_ids=$ROLE_ID1&role_ids=$ROLE_ID2&dvobject_types=$DVTYPE1&dvobject_types=$DVTYPE2&published_states=$PUBLISHED_STATE1&published_states=$PUBLISHED_STATE2&per_page=$PER_PAGE" The fully expanded example above (without environment variables) looks like this: @@ -8877,34 +8879,26 @@ The fully expanded example above (without environment variables) looks like this curl -H "X-Dataverse-key:xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx" https://demo.dataverse.org/api/mydata/retrieve?role_ids=6&role_ids=8&dvobject_types=Dataset&published_states=Unpublished&published_states=Published&per_page=10 -Parameters: - -``role_ids`` Roles are customizable. Multiple "role_ids" parameters can be used to filter by several roles. Standard roles include: - -- ``1`` = Admin -- ``2`` = File Downloader -- ``3`` = Dataverse + Dataset Creator -- ``4`` = Dataverse Creator -- ``5`` = Dataset Creator -- ``6`` = Contributor -- ``7`` = Curator -- ``8`` = Member - -``dvobject_types`` Type of object, several possible values among: ``DataFile`` , ``Dataset`` & ``Dataverse`` . - -``published_states`` State of the object. Multiple "published_states" parameters can be used. Several possible values among: ``Published`` , ``Unpublished`` , ``Draft`` , ``Deaccessioned`` & ``In+Review`` - -``per_page`` Number of results returned per page. - -``metadata_fields`` Includes the requested fields for each dataset in the response. Multiple "metadata_fields" parameters can be used to include several fields. See :doc:`search` for further information on this parameter. - -``show_collections`` Whether or not to include a list of parent and linked collections for each dataset search result. - -``sort`` The sort field. Supported values include "name", "date" and "relevance". - -``order`` The order in which to sort. Can either be "asc" or "desc". - -``fq`` A filter query (Solr syntax) to narrow the list returned. Multiple "fq" parameters can be used. +**Parameters:** + +* ``role_ids``: Roles are customizable. Multiple "role_ids" parameters can be used to filter by several roles. Standard roles include: + * ``1`` = Admin + * ``2`` = File Downloader +* ``dvobject_types``: Type of object. Multiple "dvobject_types" parameters can be used. Possible values: + * ``Dataverse`` + * ``Dataset`` + * ``DataFile`` +* ``published_states``: State of the object. Multiple "published_states" parameters can be used. Possible values: + * ``Published`` + * ``Unpublished`` + * ``Draft`` + * ``Deaccessioned`` + * ``In+Review`` +* ``mydata_search_term``: A string used to search for specific data within the user's MyData collection. +* ``selected_page``: The page number of results to return (used for pagination). +* ``per_page``: Number of results returned per page. +* ``order``: The order in which to sort. Can either be "asc" or "desc". +* ``fq``: A filter query (Solr syntax) to narrow the list returned. Multiple "fq" parameters can be used. MyData Collection List ~~~~~~~~~~~~~~~~~~~~~~ From 6e29c586b36474484f0eea9a7e7c38ff5cf9028f Mon Sep 17 00:00:00 2001 From: Philip Durbin Date: Mon, 30 Mar 2026 10:42:26 -0400 Subject: [PATCH 4/4] various tweaks --- doc/sphinx-guides/source/api/native-api.rst | 55 +++++++++++---------- 1 file changed, 30 insertions(+), 25 deletions(-) diff --git a/doc/sphinx-guides/source/api/native-api.rst b/doc/sphinx-guides/source/api/native-api.rst index 8005352c5c2..c91c45defae 100644 --- a/doc/sphinx-guides/source/api/native-api.rst +++ b/doc/sphinx-guides/source/api/native-api.rst @@ -8852,15 +8852,15 @@ Note that this API is probably only useful for testing. MyData ------ -The MyData API is used to get a list of just the datasets, dataverses or datafiles an authenticated user can edit. +The MyData API is used to get a list of just the datasets, collections (dataverses), or datafiles an authenticated user has a role on. -The API excludes dataverses linked to an harvesting client. This results in `a known issue `_ where regular datasets in harvesting dataverses are missing from the results. +The API excludes collections linked to an harvesting client. This results in `a known issue `_ where regular datasets in harvesting collections are missing from the results. -A curl example listing objects +Here is a curl example. .. code-block:: bash -export API_TOKEN=xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx + export API_TOKEN=xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx export SERVER_URL=https://demo.dataverse.org export ROLE_ID1=6 export ROLE_ID2=8 @@ -8870,35 +8870,40 @@ export API_TOKEN=xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx export PUBLISHED_STATE2=Published export PER_PAGE=10 - curl -H "X-Dataverse-key:$API_TOKEN" \ - "$SERVER_URL/api/mydata/retrieve?role_ids=$ROLE_ID1&role_ids=$ROLE_ID2&dvobject_types=$DVTYPE1&dvobject_types=$DVTYPE2&published_states=$PUBLISHED_STATE1&published_states=$PUBLISHED_STATE2&per_page=$PER_PAGE" + curl -H "X-Dataverse-key:$API_TOKEN" "$SERVER_URL/api/mydata/retrieve?role_ids=$ROLE_ID1&role_ids=$ROLE_ID2&dvobject_types=$DVTYPE1&dvobject_types=$DVTYPE2&published_states=$PUBLISHED_STATE1&published_states=$PUBLISHED_STATE2&per_page=$PER_PAGE" The fully expanded example above (without environment variables) looks like this: .. code-block:: bash - curl -H "X-Dataverse-key:xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx" https://demo.dataverse.org/api/mydata/retrieve?role_ids=6&role_ids=8&dvobject_types=Dataset&published_states=Unpublished&published_states=Published&per_page=10 + curl -H "X-Dataverse-key:xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx" "https://demo.dataverse.org/api/mydata/retrieve?role_ids=6&role_ids=8&dvobject_types=Dataset&published_states=Unpublished&published_states=Published&per_page=10" **Parameters:** -* ``role_ids``: Roles are customizable. Multiple "role_ids" parameters can be used to filter by several roles. Standard roles include: - * ``1`` = Admin - * ``2`` = File Downloader -* ``dvobject_types``: Type of object. Multiple "dvobject_types" parameters can be used. Possible values: - * ``Dataverse`` - * ``Dataset`` - * ``DataFile`` -* ``published_states``: State of the object. Multiple "published_states" parameters can be used. Possible values: - * ``Published`` - * ``Unpublished`` - * ``Draft`` - * ``Deaccessioned`` - * ``In+Review`` -* ``mydata_search_term``: A string used to search for specific data within the user's MyData collection. -* ``selected_page``: The page number of results to return (used for pagination). -* ``per_page``: Number of results returned per page. -* ``order``: The order in which to sort. Can either be "asc" or "desc". -* ``fq``: A filter query (Solr syntax) to narrow the list returned. Multiple "fq" parameters can be used. +- ``role_ids``: Roles are customizable. Multiple "role_ids" parameters can be used to include several roles. Standard roles include: + - ``1`` = Admin + - ``2`` = File Downloader + - ``3`` = Dataverse + Dataset Creator + - ``4`` = Dataverse Creator + - ``5`` = Dataset Creator + - ``6`` = Contributor + - ``7`` = Curator + - ``8`` = Member +- ``dvobject_types``: Type of object. Multiple "dvobject_types" parameters can be used to include several types. Possible values: + - ``Dataverse`` + - ``Dataset`` + - ``DataFile`` +- ``published_states``: State of the object. Multiple "published_states" parameters can be used to include several states. Possible values: + - ``Published`` + - ``Unpublished`` + - ``Draft`` + - ``Deaccessioned`` + - ``In+Review`` (the ``+`` represents a space) +- ``mydata_search_term``: A string used to search for specific data within the user's MyData collection. +- ``selected_page``: The page number of results to return (used for pagination). +- ``per_page``: Number of results returned per page. +- ``order``: The order in which to sort. Can either be "asc" or "desc". +- ``fq``: A filter query (Solr syntax) to narrow the list returned. Multiple "fq" parameters can be used. MyData Collection List ~~~~~~~~~~~~~~~~~~~~~~