Merge pull request #12140 from dsd-sztaki-hu/preview-url-token-as-api-token-doc

document preview URL token usage as API key

Author: pdurbin

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
 -------------
 

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
 ---------------------------------
 

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-file-using-preview-url-token>`.
+
 
 .. _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