Frequently Asked Questions¶
APIs are less intuitive than graphical user interfaces (GUIs) so questions are expected!
See the Getting Started with APIs section links to examples using curl.
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.
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
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.
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 if you deploy Dataverse Software 5.x. For details, see https://github.com/IQSS/dataverse/issues/5794
No, but there probably should be. If you have suggestions for how it should look, please create an issue at https://github.com/IQSS/dataverse/issues
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:
Setting a logo image, URL, and tagline when creating a Dataverse collection.
Editing properties of an existing Dataverse collection.
Downloading a guestbook.
Set guestbook_id for a dataset: https://groups.google.com/d/msg/dataverse-community/oKdesT9rFGc/qM6wrsnnBAAJ
Filling out a guestbook. See also https://groups.google.com/d/msg/dataverse-dev/G9FNGP_bT0w/dgE2Fk4iBQAJ
Seeing why a file failed ingest.
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 Developer Guide for instructions.
They should be. Please consider making a pull request to help. The Writing Documentation section of the Developer 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.