Skip to content

Latest commit

 

History

History
146 lines (86 loc) · 4.34 KB

getting-started.rst

File metadata and controls

146 lines (86 loc) · 4.34 KB
Raw

Getting Started with APIs

If you are a researcher or curator who wants to automate parts of your workflow, this section should help you get started. The intro section lists resources for other groups who may be interested in Dataverse APIs such as developers of integrations and support teams.

Servers You Can Test With

Rather than using a production installation of Dataverse, API users are welcome to use http://demo.dataverse.org for testing. You can email support@dataverse.org if you have any trouble with this server.

If you would rather have full control over your own test server, deployments to AWS, Docker, Vagrant, and more are covered in the /developers/index and the /installation/index.

Getting an API Token

Many Dataverse APIs require an API token.

Once you have identified a server to test with, create an account, click on your name, and get your API token. For more details, see the auth section.

curl Examples and Environment Variables --------------------------------------

The examples in this guide use curl for the following reasons:

  • curl commands are succinct.
  • curl commands can be copied and pasted into a terminal.
  • This guide is programming language agnostic. It doesn't prefer any particular programming language.

You'll find curl examples that look like this:

export SERVER_URL=https://demo.dataverse.org
export QUERY=data

curl $SERVER_URL/api/search?q=$QUERY

What's going on above is the declaration of "environment variables" that are substituted into a curl command. You should run the "export" commands but change the value for the server URL or the query (or whatever options the command supports). Then you should be able to copy and paste the curl command and it should "just work", substituting the variables like this:

curl https://demo.dataverse.org/api/search?q=data

If you ever want to check an environment variable, you can "echo" it like this:

echo $SERVER_URL

If you don't like curl, don't have curl, or want to use a different programming language, you are encouraged to check out the Python, R, and Java options in the client-libraries section.

Depositing Data

Creating a Dataverse

See create-dataverse-api.

Creating a Dataset

See create-dataset-command.

Uploading Files

See add-file-api.

Publishing a Dataverse

See publish-dataverse-api.

Publishing a Dataset

See publish-dataset-api.

Finding and Downloading Data

Finding Datasets

A quick example search for the word "data" is https://demo.dataverse.org/api/search?q=data

See the search section for details.

Downloading Files

The dataaccess section explains how to download files.

In order to download files, you must know their database IDs which you can get from the dataverse_json metadata at the dataset level. See export-dataset-metadata-api.

Downloading Metadata

Dataset metadata is available in a variety of formats listed at metadata-export-formats.

See export-dataset-metadata-api.

Listing the Contents of a Dataverse

See show-contents-of-a-dataverse-api.

Managing Permissions

Granting Permission

See assign-role-on-a-dataverse-api.

Revoking Permission

See revoke-role-on-a-dataverse-api.

Listing Permissions (Role Assignments)

See list-role-assignments-on-a-dataverse-api.

Beyond "Getting Started" Tasks

In addition to the tasks listed above, Dataverse supports many other operations via API.

See list-of-dataverse-apis and types-of-api-users to get oriented.

If you're looking for some inspiration for how you can use Dataverse APIs, there are open source projects that integrate with Dataverse listed in the apps section.

Getting Help

See getting-help-with-apis.