From d5761271fb9ed00d1bb0236a7a97779cb4ce1898 Mon Sep 17 00:00:00 2001 From: sirineREKIK Date: Tue, 16 May 2023 09:34:12 +0200 Subject: [PATCH 1/9] add MyData API to dataverse documentaion --- doc/sphinx-guides/source/api/native-api.rst | 37 +++++++++++++++++++++ 1 file changed, 37 insertions(+) diff --git a/doc/sphinx-guides/source/api/native-api.rst b/doc/sphinx-guides/source/api/native-api.rst index 6f10b28f55b..09096667650 100644 --- a/doc/sphinx-guides/source/api/native-api.rst +++ b/doc/sphinx-guides/source/api/native-api.rst @@ -4505,6 +4505,43 @@ A curl example using allowing access to a dataset's metadata Please see :ref:`dataverse.api.signature-secret` for the configuration option to add a shared secret, enabling extra security. + +MyData +----- + +The MyData API is used to get a list of just the datasets, dataverses or datafiles an authenticated user can edit. + +MyData API +~~~~~~~~~~~~~~~~~~~~~~~~~~ + +List objects:: + +.. 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 PER_PAGE=10 + + curl -H GET http://$SERVER_URL/api/mydata/retrieve?key=$API_TOKEN&role_ids=$ROLE_IDS&dvobject_types=$DVOBJECT_TYPES&published_states=$PUBLISHED_STATES&per_page=$PER_PAGE + +``key`` is the user token, for this API is must not be passed in the header. +``role_id`` User roles, several possible values among: +- ``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 + + .. _send-feedback: Send Feedback To Contact(s) From 17927026dbc9bf0148f68234f2c39ab58526f799 Mon Sep 17 00:00:00 2001 From: sirineREKIK Date: Tue, 16 May 2023 15:06:20 +0200 Subject: [PATCH 2/9] fix sphinx error --- doc/sphinx-guides/source/api/native-api.rst | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/doc/sphinx-guides/source/api/native-api.rst b/doc/sphinx-guides/source/api/native-api.rst index 09096667650..20050219c2f 100644 --- a/doc/sphinx-guides/source/api/native-api.rst +++ b/doc/sphinx-guides/source/api/native-api.rst @@ -4507,12 +4507,12 @@ security. MyData ------ +------ The MyData API is used to get a list of just the datasets, dataverses or datafiles an authenticated user can edit. MyData API -~~~~~~~~~~~~~~~~~~~~~~~~~~ +~~~~~~~~~~ List objects:: From ccd295fa3fc43fbf2d6d0ab43e0ac8acaab4eedb Mon Sep 17 00:00:00 2001 From: sirineREKIK Date: Tue, 16 May 2023 15:25:45 +0200 Subject: [PATCH 3/9] fix layout --- doc/sphinx-guides/source/api/native-api.rst | 12 ++++++++---- 1 file changed, 8 insertions(+), 4 deletions(-) diff --git a/doc/sphinx-guides/source/api/native-api.rst b/doc/sphinx-guides/source/api/native-api.rst index 20050219c2f..83084411fa7 100644 --- a/doc/sphinx-guides/source/api/native-api.rst +++ b/doc/sphinx-guides/source/api/native-api.rst @@ -4514,7 +4514,7 @@ The MyData API is used to get a list of just the datasets, dataverses or datafil MyData API ~~~~~~~~~~ -List objects:: +A curl example listing objects .. code-block:: bash @@ -4527,8 +4527,11 @@ List objects:: curl -H GET http://$SERVER_URL/api/mydata/retrieve?key=$API_TOKEN&role_ids=$ROLE_IDS&dvobject_types=$DVOBJECT_TYPES&published_states=$PUBLISHED_STATES&per_page=$PER_PAGE +Parameters: + ``key`` is the user token, for this API is must not be passed in the header. ``role_id`` User roles, several possible values among: + - ``1`` = Admin - ``2`` = File Downloader - ``3`` = Dataverse + Dataset Creator @@ -4537,9 +4540,10 @@ List objects:: - ``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 + +``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. .. _send-feedback: From 0587a7a80f664254a2cb635501fcc34e7b736d41 Mon Sep 17 00:00:00 2001 From: sirineREKIK Date: Tue, 16 May 2023 15:47:41 +0200 Subject: [PATCH 4/9] change position api documentation --- doc/sphinx-guides/source/api/native-api.rst | 57 +++++++++++---------- 1 file changed, 30 insertions(+), 27 deletions(-) diff --git a/doc/sphinx-guides/source/api/native-api.rst b/doc/sphinx-guides/source/api/native-api.rst index 83084411fa7..2380a5142da 100644 --- a/doc/sphinx-guides/source/api/native-api.rst +++ b/doc/sphinx-guides/source/api/native-api.rst @@ -4506,6 +4506,33 @@ Please see :ref:`dataverse.api.signature-secret` for the configuration option to security. +.. _send-feedback: + +Send Feedback To Contact(s) +~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +This API call allows sending an email to the contacts for a collection, dataset, or datafile or to the support email address when no object is specified. +The call is protected by the normal /admin API protections (limited to localhost or requiring a separate key), but does not otherwise limit the sending of emails. +Administrators should be sure only trusted applications have access to avoid the potential for spam. + +The call is a POST with a JSON object as input with four keys: +- "targetId" - the id of the collection, dataset, or datafile. Persistent ids and collection aliases are not supported. (Optional) +- "subject" - the email subject line +- "body" - the email body to send +- "fromEmail" - the email to list in the reply-to field. (Dataverse always sends mail from the system email, but does it "on behalf of" and with a reply-to for the specified user.) + +A curl example using an ``ID`` + +.. code-block:: bash + + export SERVER_URL=http://localhost + export JSON='{"targetId":24, "subject":"Data Question", "body":"Please help me understand your data. Thank you!", "fromEmail":"dataverseSupport@mailinator.com"}' + + curl -X POST -H 'Content-Type:application/json' -d "$JSON" $SERVER_URL/api/admin/feedback + +Note that this call could be useful in coordinating with dataset authors (assuming they are also contacts) as an alternative/addition to the functionality provided by :ref:`return-a-dataset`. + + MyData ------ @@ -4541,33 +4568,9 @@ Parameters: - ``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. - - -.. _send-feedback: - -Send Feedback To Contact(s) -~~~~~~~~~~~~~~~~~~~~~~~~~~~ - -This API call allows sending an email to the contacts for a collection, dataset, or datafile or to the support email address when no object is specified. -The call is protected by the normal /admin API protections (limited to localhost or requiring a separate key), but does not otherwise limit the sending of emails. -Administrators should be sure only trusted applications have access to avoid the potential for spam. - -The call is a POST with a JSON object as input with four keys: -- "targetId" - the id of the collection, dataset, or datafile. Persistent ids and collection aliases are not supported. (Optional) -- "subject" - the email subject line -- "body" - the email body to send -- "fromEmail" - the email to list in the reply-to field. (Dataverse always sends mail from the system email, but does it "on behalf of" and with a reply-to for the specified user.) +``dvobject_types`` Type of object, several possible values among: ``DataFile`` , ``Dataset`` & ``Dataverse`` . -A curl example using an ``ID`` - -.. code-block:: bash +``published_states`` State of the object, several possible values among:``Published`` , ``Unpublished`` , ``Draft`` , ``Deaccessioned`` & ``In+Review`` . - export SERVER_URL=http://localhost - export JSON='{"targetId":24, "subject":"Data Question", "body":"Please help me understand your data. Thank you!", "fromEmail":"dataverseSupport@mailinator.com"}' - - curl -X POST -H 'Content-Type:application/json' -d "$JSON" $SERVER_URL/api/admin/feedback +``per_page`` Number of results returned per page. -Note that this call could be useful in coordinating with dataset authors (assuming they are also contacts) as an alternative/addition to the functionality provided by :ref:`return-a-dataset`. From 58452dbdc41782054953dbbc45eaf7fb4751205a Mon Sep 17 00:00:00 2001 From: sirineREKIK Date: Thu, 1 Jun 2023 13:22:25 +0200 Subject: [PATCH 5/9] change description of Roles --- doc/sphinx-guides/source/api/native-api.rst | 5 +++-- 1 file changed, 3 insertions(+), 2 deletions(-) diff --git a/doc/sphinx-guides/source/api/native-api.rst b/doc/sphinx-guides/source/api/native-api.rst index 2380a5142da..f663c1fb306 100644 --- a/doc/sphinx-guides/source/api/native-api.rst +++ b/doc/sphinx-guides/source/api/native-api.rst @@ -4556,8 +4556,9 @@ A curl example listing objects Parameters: -``key`` is the user token, for this API is must not be passed in the header. -``role_id`` User roles, several possible values among: +``key`` Is the user token, for this API is must not be passed in the header. + +``role_id`` Roles are customizable. Standard roles include: - ``1`` = Admin - ``2`` = File Downloader From b80e3e95dc5f708712b1b37e6e7e6cfd55c4a250 Mon Sep 17 00:00:00 2001 From: sirineREKIK <110403723+sirineREKIK@users.noreply.github.com> Date: Fri, 2 Jun 2023 14:36:59 +0200 Subject: [PATCH 6/9] Update doc/sphinx-guides/source/api/native-api.rst Co-authored-by: Philip Durbin --- doc/sphinx-guides/source/api/native-api.rst | 3 --- 1 file changed, 3 deletions(-) diff --git a/doc/sphinx-guides/source/api/native-api.rst b/doc/sphinx-guides/source/api/native-api.rst index f663c1fb306..2ec89c9bf14 100644 --- a/doc/sphinx-guides/source/api/native-api.rst +++ b/doc/sphinx-guides/source/api/native-api.rst @@ -4538,9 +4538,6 @@ MyData The MyData API is used to get a list of just the datasets, dataverses or datafiles an authenticated user can edit. -MyData API -~~~~~~~~~~ - A curl example listing objects .. code-block:: bash From b14e06ad3420f601b760e83b371c69553cb48d94 Mon Sep 17 00:00:00 2001 From: sirineREKIK Date: Fri, 2 Jun 2023 16:43:58 +0200 Subject: [PATCH 7/9] curl url improvement --- doc/sphinx-guides/source/api/native-api.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/doc/sphinx-guides/source/api/native-api.rst b/doc/sphinx-guides/source/api/native-api.rst index 2ec89c9bf14..6b1bc72fea1 100644 --- a/doc/sphinx-guides/source/api/native-api.rst +++ b/doc/sphinx-guides/source/api/native-api.rst @@ -4549,7 +4549,7 @@ A curl example listing objects export PUBLISHED_STATES=Unpublished export PER_PAGE=10 - curl -H GET http://$SERVER_URL/api/mydata/retrieve?key=$API_TOKEN&role_ids=$ROLE_IDS&dvobject_types=$DVOBJECT_TYPES&published_states=$PUBLISHED_STATES&per_page=$PER_PAGE + curl "$SERVER_URL/api/mydata/retrieve?key=$API_TOKEN&role_ids=$ROLE_IDS&dvobject_types=$DVOBJECT_TYPES&published_states=$PUBLISHED_STATES&per_page=$PER_PAGE" Parameters: From 4bad9961847e4e636711e57136016c22d29aad1e Mon Sep 17 00:00:00 2001 From: sirineREKIK Date: Wed, 7 Jun 2023 16:14:45 +0200 Subject: [PATCH 8/9] add release note --- doc/release-notes/5042-add-mydata-doc-api.md | 2 ++ 1 file changed, 2 insertions(+) create mode 100644 doc/release-notes/5042-add-mydata-doc-api.md diff --git a/doc/release-notes/5042-add-mydata-doc-api.md b/doc/release-notes/5042-add-mydata-doc-api.md new file mode 100644 index 00000000000..5a77e266725 --- /dev/null +++ b/doc/release-notes/5042-add-mydata-doc-api.md @@ -0,0 +1,2 @@ +An API named 'MyData' is supported by Dataverse. A documentation has been added describing its use (PR #9596) +This API is used to get a list of only the objects (datasets, dataverses or datafiles) that an authenticated user can modify. From 1793b33534a9430ecb7dfd6197738b4a9a9a77aa Mon Sep 17 00:00:00 2001 From: sirineREKIK Date: Fri, 7 Jul 2023 09:18:22 +0200 Subject: [PATCH 9/9] add key in header api --- doc/sphinx-guides/source/api/native-api.rst | 4 +--- 1 file changed, 1 insertion(+), 3 deletions(-) diff --git a/doc/sphinx-guides/source/api/native-api.rst b/doc/sphinx-guides/source/api/native-api.rst index 6b1bc72fea1..11fb7c49c1c 100644 --- a/doc/sphinx-guides/source/api/native-api.rst +++ b/doc/sphinx-guides/source/api/native-api.rst @@ -4549,12 +4549,10 @@ A curl example listing objects export PUBLISHED_STATES=Unpublished export PER_PAGE=10 - curl "$SERVER_URL/api/mydata/retrieve?key=$API_TOKEN&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_IDS&dvobject_types=$DVOBJECT_TYPES&published_states=$PUBLISHED_STATES&per_page=$PER_PAGE" Parameters: -``key`` Is the user token, for this API is must not be passed in the header. - ``role_id`` Roles are customizable. Standard roles include: - ``1`` = Admin