diff --git a/doc/sphinx-guides/source/api/native-api.rst b/doc/sphinx-guides/source/api/native-api.rst index 808dbeec815..c91c45defae 100644 --- a/doc/sphinx-guides/source/api/native-api.rst +++ b/doc/sphinx-guides/source/api/native-api.rst @@ -8852,51 +8852,58 @@ 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 SERVER_URL=https://demo.dataverse.org - export ROLE_IDS=6 - export DVOBJECT_TYPES=Dataset - export PUBLISHED_STATES=Unpublished + export ROLE_ID1=6 + export ROLE_ID2=8 + 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_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=$ROLE_ID1&role_ids=$ROLE_ID2&dvobject_types=$DVTYPE1&dvobject_types=$DVTYPE2&published_states=$PUBLISHED_STATE1&published_states=$PUBLISHED_STATE2&per_page=$PER_PAGE" -Parameters: - -``role_id`` Roles are customizable. 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, 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. +The fully expanded example above (without environment variables) looks like this: -``show_collections`` Whether or not to include a list of parent and linked collections for each dataset search result. +.. code-block:: bash -``sort`` The sort field. Supported values include "name", "date" and "relevance". + 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" -``order`` The order in which to sort. Can either be "asc" or "desc". +**Parameters:** -``fq`` A filter query to filter 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 ~~~~~~~~~~~~~~~~~~~~~~