Overview

EUDAT B2SHARE HTTP REST API.#

Guidelines#

B2SHARE is the EUDAT service for storing and publishing data sets. In addition to its web-based GUI, B2SHARE offers an HTTP REST API. External applications or workflows can use this API, for example, to integrate B2SHARE with other websites like research community portals, or to allow uploads and downloads of large data sets that are not easily handled via a web browser. The API functionality is also used for metadata harvesting by external metadata catalogue services, including B2FIND.

The REST API#

B2SHARE provides a graphical, web-based interface, whose functionality is discussed in the corresponding user documentation page.

The B2HARE HTTP REST API can be used for interaction with B2SHARE via external services or applications, for example for integration with other web-sites (research community portals) or for uploading or downloading large data sets that are not easily handled via a web browser. The API can also be used for metadata harvesting, although an OAI-PMH API endpoint is also provided for this purpose. This latter API will not be discussed here. This page will explain the basic concepts, authentication and all existing HTTP requests that can currently be used. The given examples are explained using curl commands.

Basic concepts#

The B2SHARE service uses several concepts which are briefly explained below. A scientific community has the roles of creating and maintaining metadata schemas and curating the datasets which are part of a scientific domain or research project. B2SHARE users can be part of one or more communities. Some selected members of a community are also given the role of community administrators, which grants them the special rights needed for the schema definitions and record curation tasks.

Any user can upload scientific datasets into B2SHARE and thus create data records. A record is comprised of data files and associated metadata. It is a possibility to create metadata-only records. The record’s metadata consists of a set of common fixed metadata field and a set of custom metadata blocks, each block containing related metadata fields. A record is always connected to one scientific community which has the role of curating and maintaining it.

A record contains a set of common metadata fields and a set of custom metadata blocks. This metadata is not free form, however, but is governed by static schemas; the common metadata schema is set by B2SHARE and defines a superset of Dublin Core- and DataCite elements, while the schema for the custom metadata block is specific to each community and can be customized by the community administrators. The schemas are formally defined in the JSON Schema format. A special HTTP REST API call is available for retrieving the JSON Schema of a record in a specific community. In order to be accepted, the records submitted to a community must conform to the schema required by the community.

Editing and versioning records#

A data record can exist in several states. Immediately after creation a record enters the ‘draft’ state. In this state the record is only accessible by its owner and the community administraors, managers and curators, and can be freely modified: its metadata can be changed and files can be uploaded into or removed from it. A draft can be published at any time, and through this action it changes its state from ‘draft’ to ‘published’, is assigned Persistent Identifiers, and becomes publicly accessible. Please note that the list of files in a published record cannot be changed without versioning the record.

Existing published records can be versioned by creating a derivative draft that initially is a clone of the original record. This draft record can be changed in metadata but also files. The records are linked together with a common parent record so that anyone can find and compare the contents of the versioned and original record. There is no limit to the number of versions created per record. A new versioned record needs to be published before it becomes available to other users.

Using the API#

The REST API is used by making API requests using the GET, PUT, DELETE or POST methods of the standard HTTP protocol. Typically an application like curl is used to make requests, but it is also possible to do this from within your custom-built applications.

Authentication#

Although listing and accessing public data is not access-controlled, only authenticated users can use the API to its full extent. Authentication during requests is done by passing an access token along with the request. The access token is an encrypted string which can be created in the B2SHARE user profile when logged in to the web user interface. B2SHARE’s access tokens follow the OAuth 2.0 standard.

You can use the access token in two ways. Either in header, or in the query.

Authenticate with header:

curl -k -H "Authorization: Bearer ACCESS_TOKEN" https://...

Authenticate via query:

curl -k https://$b2share_host/api/records?access_token=ACCESS_TOKEN

Creating an access token#

After logging in to the B2SHARE service click your user name and select ‘Applications’. Under ‘Personal access tokens’, click ‘+ New token’ (Figure 1), enter a token name (Figure 2).

Step 1: Applications.#

B2SHAREcreate API token Figure 1. B2SHARE Personal access tokens. (Step 1: Applications)

B2SHAREcreate API token Figure 2. B2SHARE Access Token. (Step 1: Applications)

Click “Create” on the bottom of the text box. Your token is now created and immediately displayed. Please note that this is the only time the access token is visible, so copy it to a safe place.

The access token is now ready for use. Access tokens can be removed by clicking on the remove button next to each access token name.

The following shell commands will expect that the ACCESS_TOKEN environment variable is defined and contains the actual access token. The command to define this variable looks like this:

Command:

export ACCESS_TOKEN='<personal_access_token>'

example:

export ACCESS_TOKEN='LMlLGmlzwo3NtDNAqIUxbb5fxq0Mr8xmS7r8gEACogHTYRpP3EIevbbSoyba'

Notes:

Please remember to use your actual token instead of the one given as an example above.
Your token can only be used for the instance you created the token in. That means that a token for the training instance of B2SHARE will not work with the production instance of B2SHARE and vice-versa!

Requests#

The API requests are made to a URL with parameters as described below. Each URL consists of a protocol part (always ‘https://’), a hostname and a path. One of the following hostnames can be used to identify the B2SHARE instance:

https://b2share.eudat.eu - the hostname for the production site.
https://trng-b2share.eudat.eu - the hostname for the training site. Use this base URL for testing.

Notes: - Please make sure that you are not using production instances for creating test records or testing the API in general. - Make sure to add a forward-slash (‘/’) to the URL if that is required. If you forget the slash then the request is interpreted differently and you might get other results than expected. In many cases, a redirect (status code 302) or not found (status code 404) will be returned, a result that in the browser will be handled automatically, but not in a typical API request.

The curl commands in the examples of each request will expect that the HOST environment variable is defined and contains the host part of the targeted B2SHARE site, e.g.:

Command:

export B2SHARE_HOST='trng-b2share.eudat.eu'

Responses#

All request response bodies are JSON encoded (UTF-8 encoded).

A record is represented as a JSON object:

{
  "field1": "value"
}

A collection of records is represented as a JSON array of objects:

{
  "collection": [
    {
      "field1": "value",
      "field2": "value"
    },
    {
      "field1": "value",
      "field2": "value"
    }
  ]
}

Timestamps are in UTC and formatted according to ISO 8601:

{
  "updated": "YYYY-MM-DDTHH:MM:SS.ssssss+00:00"
}

In case a request fails, the body of the response body contains details about the error, for

Command:

{
  "message": "The requested URL was not found on the server.  If you entered the URL manually please check your spelling and try again.",
  "status": 404
}

Here in the message field provides a detailed description of what went wrong, while the code indicates the HTTP status code (equivalent to the request response status code).

Status codes#

The request status codes indicate whether the request was successfully received, processed and/or executed. B2SHARE follows the HTTP status codes where possible.

One of the following status codes is returned in case the request was successful:

200 : Request was successfully received and executed, see body for results

201 : Object created, see body for results

204 : No contents, this occurs when for example an object is successfully deleted

In case the request failed, the body of the response usually contains details, and one of the following status codes is returned:

400 : Request was not understood

401 : User must authenticate first, usually because no access token was provided with the request

403 : User is not authorized to perform request, missing permission to do so

404 : Requested object not found or API endpoint does not exist

Any status code greater then or equal to 500 indicates that internally something went wrong in the server. If in this case the problem persists, kindly report this to EUDAT.

A publication workflow#

The HTTP REST API does not impose a specific workflow for creating a record. The following example workflow only defines the most basic steps:

Identify a target community for your data by using the HTTP REST API List all communities function
Using the community’s identifier, retrieve the JSON Schema of the record’s metadata. The submitted metadata will have to conform to this schema. Use the Get community schema function
Create a draft record: use the Create draft record function
Upload the files into the draft record. You will have to use one HTTP request per file. Use the Upload file function
Set the complete metadata and publish the record. Use the Submit draft for publication function

Available HTTP REST API requests#

Each allowed request is described as follows:

  Description : A description of the function of the request.

  HTTP method : which HTTP protocol such as GET or POST method is used.

  URL path : grammar for the allowed paths used together with one of the base URLs above.

  Status code : the returned status code upon a successful request.

  Returns : the returned data in the body of the response upon a successful request.

  Example : an example of usage using the program curl from the command line.

Some of the requests additionally might have the following information:

  Required parameters : the parameters that need to be added to the URL.

  Required data : the data that needs to be sent with the request, the expected structure is shown in the example.

Variables in the descriptions:

RECORD_ID - identifier for a specific record, which can be in draft or published state
RECORD_HEAD_ID - head identifier for a group of record that are versions of each other
FILE_BUCKET_ID - identifier for a set of files. Each record has its own file set, usually found in the links -> files section
COMMUNITY_ID - identifier of a user community in B2SHARE
COMMUNITY_SLUG - short name (slug) of a user community in B2SHARE
SCHEMA_ID - identifier of a metadata schema in B2SHARE
FILE_NAME - name of a file in a specific file bucket
FIELD_NAME - name of a metadata field

For most requests, an example is shown using a curl command. If a payload is sent with the request, this is shown in a structured way below the example. The returned response body and request-specific errors are shown if applicable.

Last update : 18.11.2025

Last review : 18.11.2025