diff --git a/doc/sphinx-guides/source/api/auth.rst b/doc/sphinx-guides/source/api/auth.rst index 8dffb914e29..f2f65bc1d15 100644 --- a/doc/sphinx-guides/source/api/auth.rst +++ b/doc/sphinx-guides/source/api/auth.rst @@ -66,6 +66,24 @@ You can reset your API Token from your account page in your Dataverse installati .. _bearer-tokens: +Using Preview URL Tokens as API Token +-------------------------------------- + +If you want to access a dataset's contents shared by a preview URL (see :ref:`previewUrl`, :ref:`get-file-using-preview-url-token`, :ref:`get-dataset-by-preview-url-token` and :ref:`create-a-preview-url-for-a-dataset`) using the API, you can use the token in the preview URL as API_TOKEN. + +.. code-block:: bash + + SERVER_URL=https://demo.dataverse.org + PREVIEW_URL_TOKEN=a56444bc-7697-4711-8964-e0577f055fd2 + + # this gets you the file listing with the corresponding file IDs, file names and other file metadata + curl "$SERVER_URL/api/datasets/privateUrlDatasetVersion/$PREVIEW_URL_TOKEN" + + # this gets you a specific file + FILE_ID=1111111 + FILENAME=example.txt + curl -H "X-Dataverse-key:$PREVIEW_URL_TOKEN" -o "$FILENAME" "$SERVER_URL/api/access/datafile/$FILE_ID" + Bearer Tokens ------------- diff --git a/doc/sphinx-guides/source/api/dataaccess.rst b/doc/sphinx-guides/source/api/dataaccess.rst index 0782665776d..b8b103b76ed 100755 --- a/doc/sphinx-guides/source/api/dataaccess.rst +++ b/doc/sphinx-guides/source/api/dataaccess.rst @@ -168,6 +168,23 @@ The fully expanded example above (without environment variables) looks like this curl -H "Range:bytes=0-9" https://demo.dataverse.org/api/access/datafile/42 + +.. _get-file-using-preview-url-token: + +Using a Preview URL Token +~~~~~~~~~~~~~~~~~~~~~~~~~ + +If you want to access a file in a dataset shared by a preview URL (see :ref:`previewUrl`, :ref:`get-dataset-by-preview-url-token` and :ref:`create-a-preview-url-for-a-dataset`) using the API, you can use the token in the preview URL as API_TOKEN. + +.. code-block:: bash + + SERVER_URL=https://demo.dataverse.org + PREVIEW_URL_TOKEN=a56444bc-7697-4711-8964-e0577f055fd2 + FILE_ID=1111111 + FILENAME=example.txt + curl -H "X-Dataverse-key:$PREVIEW_URL_TOKEN" -o "$FILENAME" "$SERVER_URL/api/access/datafile/$FILE_ID" + + Multiple File ("bundle") download --------------------------------- diff --git a/doc/sphinx-guides/source/api/native-api.rst b/doc/sphinx-guides/source/api/native-api.rst index eab71f8623b..6f382b47c57 100644 --- a/doc/sphinx-guides/source/api/native-api.rst +++ b/doc/sphinx-guides/source/api/native-api.rst @@ -2808,6 +2808,8 @@ The fully expanded example above (without environment variables) looks like this curl -H "X-Dataverse-key:xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx" -X DELETE "https://demo.dataverse.org/api/datasets/2347/assignments/6" +.. _create-a-preview-url-for-a-dataset: + Create a Preview URL for a Dataset ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ @@ -3914,6 +3916,8 @@ Like :ref:`get-export-formats`, this API can be used to get URLs to dataset meta curl -H "Accept:application/json" "$SERVER_URL/api/datasets/:persistentId/versions/$VERSION/linkset?persistentId=$PERSISTENT_IDENTIFIER" +.. _get-dataset-by-preview-url-token: + Get Dataset By Preview URL Token ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ @@ -3932,6 +3936,8 @@ Usage example: curl "https://demo.dataverse.org/api/datasets/previewUrlDatasetVersion/a56444bc-7697-4711-8964-e0577f055fd2?returnOwners=true" +For downloading files using a preview URL token, see the :ref:`Data Access API `. + .. _get-citation: @@ -3997,6 +4003,7 @@ Get Citation by Preview URL Token curl "$SERVER_URL/api/datasets/previewUrlDatasetVersion/$PREVIEW_URL_TOKEN/citation" + .. _get-dataset-summary-field-names: Get Summary Field Names