Frequently Asked Questions

APIs are less intuitive than graphical user interfaces (GUIs) so questions are expected!

What is an API?

See “What is an API?” in the Introduction section.

What Are Common Use Cases for Dataverse Software APIs?

See the Getting Started with APIs section for common use cases for researchers and curators. Other types of API users should find starting points at Types of Dataverse Software API Users.

Where Can I Find Examples of Using Dataverse Software APIs?

See the Getting Started with APIs section links to examples using curl.

For examples in Javascript, Python, R, and Java, and PHP, see the Apps and Client Libraries sections.

When Should I Use the Native API vs. the SWORD API?

The SWORD API is based on a standard, works fine, and is fully supported, but much more development effort has been going into the Native API, which is not based on a standard. It is specific to the Dataverse Software.

SWORD uses XML. The Native API uses JSON.

SWORD only supports a dozen or so operations. The Native API supports many more.

To Operate on a Dataset Should I Use Its DOI (or Handle) or Its Database ID?

It is fine to target a dataset using either its Persistent ID (PID such as DOI or Handle) or its database id.

Here’s an example from Publish a Dataset of targeting a dataset using its DOI:

curl -H X-Dataverse-key:xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx -X POST "https://demo.dataverse.org/api/datasets/:persistentId/actions/:publish?persistentId=doi:10.5072/FK2/J8SJZB&type=major"

You can target the same dataset with its database ID (“42” in the example below), like this:

curl -H X-Dataverse-key:xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx -X POST "https://demo.dataverse.org/api/datasets/42/actions/:publish?type=major"

Note that when multiple query parameters are used (such as persistentId and type above) there is a question mark (?) before the first query parameter and ampersands (&) before each of the subsequent query parameters. Also, & has special meaning in Unix shells such as Bash so you must put quotes around the entire URL.

Where is the Comprehensive List of All API Functionality?

There are so many Dataverse Software APIs that a single page in this guide would probably be overwhelming. See Lists of Dataverse APIs for links to various pages.

It is possible to get a complete list of API functionality in Swagger/OpenAPI format. See Getting the OpenAPI Document.

Is There a Changelog of API Functionality That Has Been Added Over Time?

Changes to the API that don’t break anything can be found in the release notes of each release. Breaking changes are documented in API Changelog (Breaking Changes).

What Functionality is GUI Only and Not Available Via API

The following tasks cannot currently be automated via API because no API exists for them. The web interface should be used instead for these GUI-only features:

If you would like APIs for any of the features above, please open a GitHub issue at https://github.com/IQSS/dataverse/issues

You are also welcome to open an issue to add to the list above. Or you are welcome to make a pull request. Please see the Writing Documentation section of the Contributor Guide for instructions.

Why Are the Return Values (HTTP Status Codes) Not Documented?

They should be. Please consider making a pull request to help. The Writing Documentation section of the Contriburor Guide should help you get started. Create a Dataverse Collection has an example you can follow or you can come up with a better way.

Also, please note that we are starting to experiment with putting response codes in our OpenAPI document. See Getting the OpenAPI Document.

What If My Question Is Not Answered Here?

Please ask! For information on where to ask, please see Getting Help.