Introduction

Dataverse APIs allow users to accomplish many tasks such as...

  • creating datasets
  • uploading files
  • publishing datasets
  • and much, much more

... all without using the Dataverse web interface.

APIs open the door for integrations between Dataverse and other software. For a list, see the Integrations section of the Admin Guide.

What is an API?

API stands for “Application Programming Interface” and an example is Dataverse’s “file upload” API. In the diagram below, we can see that while users can click a button within Dataverse’s web interface to upload a file, there are many other ways to get files into Dataverse, all using an API that allows for uploading of files.

digraph {
  //rankdir="LR";
  node [fontsize=10]

    browser [label="Web Browser"]
    terminal [label="Terminal"]

    osf [label="OSF",shape=box]
    ojs [label="OJS",shape=box]
    rspace [label="RSpace",shape=box]
    uploader [label="DvUploader"]
    script [label="Script\n(Python,\nR, etc.)"]

    addfilebutton [label="Add File GUI"]
    addfileapi [label="Add File API"]
    storage [label="Storage",shape=box3d]

    terminal -> script
    terminal -> uploader

    browser -> ojs
    browser -> osf
    browser -> rspace
    browser -> addfilebutton

    uploader -> addfileapi
    ojs -> addfileapi
    osf -> addfileapi
    rspace -> addfileapi
    script -> addfileapi

    subgraph cluster_dataverse {
      label="Dataverse"
      labeljust="r"
      labelloc="b"
      addfilebutton -> storage
      addfileapi -> storage
    }
}

The components above that use the “file” upload API are:

  • DvUploader is terminal-based application for uploading files that is described in the Dataset + File Management section of the User Guide.
  • OJS, OSF, and RSpace are all web applications that can integrate with Dataverse and are described in “Getting Data In” in the Integrations section of the Admin Guide.
  • The script in the diagram can be as simple as a single line of code that is run in a terminal. You can copy and paste “one-liners” like this from the guide. See the Getting Started with APIs section for examples using a tool called “curl”.

The diagram above shows only a few examples of software using a specific API but many more APIs are available.

Types of Dataverse API Users

This guide is intended to serve multiple audiences but pointers various sections of the guide are provided below based on the type of API user you are.

API Users Within a Single Installation of Dataverse

Each installation of Dataverse will have its own groups of people interested in APIs.

Users of Integrations and Apps

Integrations and apps can take many forms but two examples are:

  • Using Open Science Framework (OSF), a web application, to deposit and publish data into Dataverse.
  • Using DVUploader, a terminal-based desktop application, to upload files into Dataverse.

In both examples, users need to obtain an API Token to authenticate with Dataverse.

Starting point   A good starting point is “API Tokens” in the Account Creation + Management section of the User Guide. DvUploader is documented in the Dataset + File Management section of the User Guide. The integrations that are enabled depend on your installation of Dataverse. You can find a list in the Integrations section of the Admin Guide.

Power Users

Power users may be researchers or curators who are comfortable with automating parts of their workflow by writing Python code or similar.

Starting point   The recommended starting point for power users is the Getting Started with APIs section.

Support Teams and Superusers

Support teams that answer questions about their installation of Dataverse should familiarize themselves with the Getting Started with APIs section to get a sense of common tasks that researchers and curators might be trying to accomplish by using Dataverse APIs.

Superusers of an installation of Dataverse have access a superuser dashboard described in the Dashboard section of the Admin Guide but some operations can only be done via API.

Starting point   A good starting point for both groups is the Getting Started with APIs section of this guide followed by the Troubleshooting section of the Admin Guide.

Sysadmins

Sysadmins often write scripts to automate tasks and Dataverse APIs make this possible. Sysadmins have control over the server that Dataverse is running on and may be called upon to execute API commands that are limited to “localhost” (the server itself) for security reasons.

Starting point   A good starting point for sysadmins is “Blocking API Endpoints” in the Configuration section of the Installation Guide, followed by the Getting Started with APIs section of this guide, followed by the Troubleshooting section of the Admin Guide.

In House Developers

Some organizations that run Dataverse employ developers who are tasked with using Dataverse APIs to accomplish specific tasks such as building custom integrations with in house systems or creating reports specific to the organization’s needs.

Starting point   A good starting point for in house developers is the Getting Started with APIs section.

API Users Across the Dataverse Project

The Dataverse project loves contributors! Depending on your interests and skills, you might fall into one or more of the groups below.

Developers of Integrations, External Tools, and Apps

One of the primary purposes for Dataverse APIs in the first place is to enable integrations with third party software. Integrations are listed in the following places:

Starting point   Good starting points are the three sections above to get a sense of third-party software that already integrates with Dataverse, followed by the Getting Started with APIs section.

Developers of Dataverse API Client Libraries

A client library helps developers using a specific programming language such as Python, R, or Java interact with Dataverse APIs in a manner that is idiomatic for their language. For example, a Python programmer may want to

Starting point   A good starting point is the Client Libraries section, followed by the Getting Started with APIs section.

Developers of Dataverse Itself

Developers working on Dataverse itself use Dataverse APIs when adding features, fixing bugs, and testing those features and bug fixes.

Starting point   A good starting point is the Testing section of the Developer Guide.

How This Guide is Organized

Lists of Dataverse APIs

  • Search API: For searching dataverses, datasets, and files.
  • Data Access API: For downloading and subsetting data.
  • Native API: For performing most tasks that are possible in the GUI. See Getting Started with APIs for the most common commands which operate on endpoints with names like:
    • Dataverses
    • Datasets
    • Files
    • etc.
  • Metrics API: For query statistics about usage of a Dataverse installation.
  • SWORD API: For depositing data using a standards-based approach rather than the Native API.

Please note that some APIs are only documented in other guides that are more suited to their audience:

Client Libraries

See Client Libraries for how to use Dataverse APIs from Python, R, and Java.

Examples

Apps links to example open source code you can study. Getting Started with APIs also has many examples.

Getting Help

Dataverse API questions are on topic in all the usual places:

After your question has been answered, you are welcome to help improve the Frequently Asked Questions section of this guide.