Merge branch 'develop' into 11733-api-get-file-citation-format

Author: stevenwinship

doc/sphinx-guides/source/api/native-api.rst

@@ -8854,51 +8854,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 <https://github.com/IQSS/dataverse/issues/11083>`_ 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 <https://github.com/IQSS/dataverse/issues/11083>`_ 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
 ~~~~~~~~~~~~~~~~~~~~~~