Skip to content

EUDAT B2INST HTTP REST API.#

Guidelines#

B2INST is the EUDAT service for storing and publishing data sets. In addition to its web-based GUI, B2INST offers an HTTP REST API. External applications or workflows can use this API, for example, to integrate B2INST 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#

B2INST 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 B2INST 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. For usage of the API with Python, please follow the training material provided by EUDAT.

Basic concepts#

The B2INST 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. B2INST 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 B2INST and thus create data records. A record is comprised of data files and associated metadata. The record’s metadata consists of a set of common fixed metadata fields 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 B2INST and defines a superset of Dublin Core 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 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.

To update the metadata of a record through the API, a JSON Patch must be supplied with the request. Please read the documentation on this website carefully to fully understand how these patches work. In the request below, the term ‘JSONPath’ is used which indicates a path in the metadata relative to the root of the structure.

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. A link will be established to the original 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 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. To integrate the API in your application using Python, please refer to the B2INST API training module to learn how to use the API.

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 B2INST user profile when logged in to the web user interface. B2INST’s access tokens follow the OAuth 2.0 standard.

Creating an access token#

After logging in to the B2INST service click your username and select ‘Profile’. Under ’ API tokens’, enter a token name (Figure 1).

Click “New token” on the right 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:

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 B2INST instance:

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 B2INST site, e.g.:

export B2INST_HOST='b2inst-test.gwdg.de'

Responses#

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:

{
    "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
}

Herein 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. B2INST follows the HTTP status codes where possible, a complete list can be found here. 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 than 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:

  1. Identify a target community for your data by using the HTTP REST API List all communities function
  2. 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
  3. Create a draft record: use the Create draft record function
  4. Upload the files into the draft record. You will have to use one HTTP request per file. Use the Upload file function
  5. 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 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 B2INST

SCHEMA_ID - identifier of a metadata schema in B2INST

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.

Object retrieval#

The following requests concern the retrieval of information about records and communities.

List all communities#

List all the communities, without any filtering.

HTTP method: GET

URL path: /api/communities/

Required parameters: None

Status code on success: 200

Returns: the list of communities (in JSON format) or an error message.
Command:#
curl "https://<B2INST_HOST>/api/communities"

Returns:

Get community schema#

Retrieves the JSON schema of records approved by a specific community.

HTTP method: GET

URL path: /api/communities/<COMMUNITY_ID>/schemas/last

Required parameters: None

Status code on success: 200

Returns: the community metadata schema, embedded in a JSON object, or an error message.
Command:#
curl "https://<B2INST_HOST>/api/communities/<COMMUNITY_ID>/schemas/last

Returns:

List all records#

List all the records, without any filtering.

HTTP method: GET

URL path: /api/records/

Required parameters: None

Optional parameters: page, size, mostrecent

Status code on success: 200

Returns: the list of records (in JSON format) or an error message.

Command: 

curl "https://<B2INST_HOST>/api/records

List records per community#

List all records of a specific community.

HTTP method: GET

URL path: /api/records/

Required parameters: q with value community: COMMUNITY_ID

Status code on success: 200

Returns: the list of records (in JSON format) or an error message
Notes:#

you can use search parameters to further narrow your search as described in the ‘Search records’ section.

Command: 

curl "https://<B2INST_HOST>/api/records/?q=community=<COMMUNITY_ID>"

Search records#

Search all the published records for a query string.

HTTP method: GET

URL path: /api/records/

Required parameters: none

Optional parameters: q, page, size, sort

Status code on success: 200

Returns: the list of matching records (in JSON format) or an error message
Command:#
curl "https://<B2INST_HOST>/api/records/?q=<QUERY_STRING>&page=1&size=100&sort=mostrecent"
Notes:#

  • The parameter q determines the keywords to search for, separated by a space.

  • If a field name is prepended followed by a colon and the search value, the search is limited to that field, e.g. ‘creators.creator:user’ searches for records with a ‘user’ in the creator metadata field.

  • If the parameter q is omitted, all records are returned (in paginated form). See also ‘List all records’.

  • For a better understanding of search queries, a listing of available search fields and advanced options like operators, please refer to the B2INST Advanced Search documentation on how to create them.

  • Using the page and size parameter, pagination can be established by providing integer values for these parameters. The page parameter is 1-based.

  • For example: using a value of 2 for page and 50 for size will return the records from number 51 to 100 (if there are at least 100 records available on the instance)

The sort parameter can be either ‘mostrecent’ or ‘bestmatch’.

Search drafts#

List all your draft records

HTTP method: GET

URL path: /api/records/

Required parameters: access_token, drafts

Optional parameters: q

Status code on success: 200

Returns: the list of matching drafts (in JSON format) or an error message.
Command:#
curl "https://<B2INST_HOST>/api/records/?drafts&access_token=<ACCESS_TOKEN>"
Notes:#

  • You can only list your own draft records.

  • You can add search parameters to narrow down your search, see ‘Search records’

Get specific record#

List the metadata of the record specified by RECORD_ID. The metadata of all records are always public.

HTTP method: GET

URL path: /api/records/RECORD_ID

Required parameters: access_token

Status code on success: 200

Command: curl "https://<B2INST_HOST>/api/records/<RECORD_ID>"

Notes:#
  • The access token is only required when a record is not publicly available.

Record administration#

The following requests concern the creation, update and management of records.

Create draft record:#

Create a new record, in the draft state.

HTTP method: POST

URL path: /api/records/

Required parameters: access_token

Payload data: JSON object with basic metadata of the object, at least the required 
fields of the basic metadata schema of each new record: titles, community and
open_access.

Status code on success: 201

Returns: the new draft record metadata including new URL location.
Notes:#
  • Please note that the URL of the draft record, needed for setting record metadata, will end in /draft/.
Examples:#
$ curl -X POST -H "Content-Type:application/json" -d '{"title":"My dataset record","Name":"My dataset record","Description":"A simple description","community":"94a9567e-2fba-4677-8fde-a8b68bdb63e8","open_access":true}' "http://localhost:5000/api/records/?access_token=6MXcJvC74kF8Z7DSipBcZWko2D5iLQN5hjdt0MtAREqSUPlNtlhBppO30fcW"
{
  "created": "2023-05-23T22:23:55.319451+00:00", 
  "id": "77004d595c4940e991f410b9d82f54fa", 
  "links": {
    "files": "http://localhost:5000/api/files/bc0d2e07-b331-4c33-8ff3-85e04c2972b3", 
    "publication": "http://localhost:5000/api/records/77004d595c4940e991f410b9d82f54fa", 
    "self": "http://localhost:5000/api/records/77004d595c4940e991f410b9d82f54fa/draft", 
    "versions": "http://localhost:5000/api/records/3bd707b7497e43eea6fb0706c8aabbe4/versions"
  }, 
  "metadata": {
    "$schema": "http://localhost:5000/api/communities/94a9567e-2fba-4677-8fde-a8b68bdb63e8/schemas/0#/draft_json_schema", 
    "Description": "A simple description", 
    "Name": "My dataset record", 
    "community": "94a9567e-2fba-4677-8fde-a8b68bdb63e8", 
    "open_access": true, 
    "owners": [
      3
    ], 
    "publication_state": "draft", 
    "title": "My dataset record"
  }, 
  "updated": "2023-05-23T22:23:55.319454+00:00"
}
Common errors:#

On metadata validation error: { "message": "Validation error.", "status": 400 }

The supplied metadata is invalid or incorrectly structured. This means that either a specified field does not exist in the metadata schema, or that one of the values for a given field is invalid.

Upload file into draft record:#

To upload a new file into a draft record object, first you need to identify the file bucket URL. This URL can be found in the information returned when querying a draft record, in the ‘links/files’ section of the returned data.

HTTP method: PUT

URL path: /api/files/FILE_BUCKET_ID/FILE_NAME

Required parameters: access_token

Payload data: the file, sent as direct stream, for curl use the --data-binary @FILE_NAME option for this.

Status code on success: 200

Returns: informations about the newly uploaded file
Command:#
curl -X PUT -H 'Accept:application/json' -H 'Content-Type:application/octet-stream' \
    --data-binary @<FILE_NAME> \
    "https://<B2INST_HOST>/api/files/<FILE_BUCKET_ID><FILE_NAME>?access_token=<ACCESS_TOKEN>"
Examples:#
$ curl -X PUT -H 'Accept:application/json' -H 'Content-Type:application/octet-stream' --data-binary @README.md "http://localhost:5000/api/files/bc0d2e07-b331-4c33-8ff3-85e04c2972b3/README.md?access_token=6MXcJvC74kF8Z7DSipBcZWko2D5iLQN5hjdt0MtAREqSUPlNtlhBppO30fcW"
{
  "key": "README.md", 
  "created": "2023-05-24T13:50:19.308581+00:00", 
  "size": 326, 
  "checksum": "md5:38a545c61945c806d9a2cba95427caf4", 
  "links": {
    "self": "http://localhost:5000/api/files/bc0d2e07-b331-4c33-8ff3-85e04c2972b3/README.md", 
    "version": "http://localhost:5000/api/files/bc0d2e07-b331-4c33-8ff3-85e04c2972b3/README.md?versionId=9da55ab6-3014-4d1f-b9cb-d88c18949644", 
    "uploads": "http://localhost:5000/api/files/bc0d2e07-b331-4c33-8ff3-85e04c2972b3/README.md?uploads"
  }, 
  "is_head": true, 
  "delete_marker": false, 
  "updated": "2023-05-24T13:50:19.311466+00:00", 
  "mimetype": "text/markdown", 
  "version_id": "9da55ab6-3014-4d1f-b9cb-d88c18949644"
}

Delete file from draft record:#

Send a DELETE request to the file’s URL, which is the same URL used for uploading.

HTTP method: DELETE

URL path: /api/files/FILE_BUCKET_ID/FILE_NAME

Required parameters: access_token

Status code on success: 204

Returns: no content
Command:#
curl -X DELETE -H 'Accept:application/json' "http://<B2INST_HOST>/api/files/<FILE_BUCKET_ID>/<FILE_NAME>?access_token=<ACCESS_TOKEN>"
Example:#
curl -X DELETE -H 'Accept:application/json' "http://localhost:5000/api/files/bc0d2e07-b331-4c33-8ff3-85e04c2972b3/README.md?access_token=6MXcJvC74kF8Z7DSipBcZWko2D5iLQN5hjdt0MtAREqSUPlNtlhBppO30fcW"

List files of record:#

List the files uploaded into a record object. For this request you need the FILE_BUCKET_ID which can be found in the metadata of the record. This does not include files that are referenced externally.

Command:#
curl "http://<B2INST_HOST>/api/files/<FILE_BUCKET_ID>?access_token=<ACCESS_TOKEN>"
Example:#
curl "http://localhost:5000/api/files/bc0d2e07-b331-4c33-8ff3-85e04c2972b3?access_token=6MXcJvC74kF8Z7DSipBcZWko2D5iLQN5hjdt0MtAREqSUPlNtlhBppO30fcW"

Update draft record metadata:#

This action updates the draft record with new information.

HTTP method: PATCH

URL path: /api/records/RECORD_ID/draft

Required parameters: access_token

Payload data: the metadata for the draft record to be updated, in the JSON Patch format (see http://jsonpatch.com/)

Status code on success: 200

Returns: the updated metadata of the draft record.
Notes:#
  • The JSON Patch format contains one or more JSONPath strings. The root of these paths are the metadata object, as this is the only mutable object. For instance, to update the title field of the record, use this JSONPath: /titles/title
Example #1:#
$ curl -X PATCH -H 'Content-Type:application/json-patch+json' -d '[{"op": "add", "path":"/Manufacturers", "value": [{"manufacturerName": "GWDG"}, {"manufacturerName": "Max Planck Society"} ]}]' "http://localhost:5000/api/records/77004d595c4940e991f410b9d82f54fa/draft?access_token=6MXcJvC74kF8Z7DSipBcZWko2D5iLQN5hjdt0MtAREqSUPlNtlhBppO30fcW"
{
  "created": "2023-05-23T22:23:55.319451+00:00", 
  "id": "77004d595c4940e991f410b9d82f54fa", 
  "links": {
    "files": "http://localhost:5000/api/files/bc0d2e07-b331-4c33-8ff3-85e04c2972b3", 
    "publication": "http://localhost:5000/api/records/77004d595c4940e991f410b9d82f54fa", 
    "self": "http://localhost:5000/api/records/77004d595c4940e991f410b9d82f54fa/draft", 
    "versions": "http://localhost:5000/api/records/3bd707b7497e43eea6fb0706c8aabbe4/versions"
  }, 
  "metadata": {
    "$schema": "http://localhost:5000/api/communities/94a9567e-2fba-4677-8fde-a8b68bdb63e8/schemas/0#/draft_json_schema", 
    "Description": "A simple description", 
    "Manufacturers": [
      {
        "manufacturerName": "GWDG"
      }, 
      {
        "manufacturerName": "Max Planck Society"
      }
    ], 
    "Name": "My dataset record", 
    "community": "94a9567e-2fba-4677-8fde-a8b68bdb63e8", 
    "open_access": true, 
    "owners": [
      3
    ], 
    "publication_state": "draft", 
    "title": "My dataset record"
  }, 
  "updated": "2023-05-24T15:51:34.596574+00:00"
}
Example #2:#
$ curl -X PATCH -H 'Content-Type:application/json-patch+json' -d '[{"op": "add", "path":"/schemaVersion", "value": {"schemaVersion": "1.2"} }]' "http://localhost:5000/api/records/77004d595c4940e991f410b9d82f54fa/draft?access_token=6MXcJvC74kF8Z7DSipBcZWko2D5iLQN5hjdt0MtAREqSUPlNtlhBppO30fcW"5iLQN5hjdt0MtAREqSUPlNtlhBppO30fcW"

{
  "status": 400,
  "message": "Validation error.",
  "errors": [
    {
      "field": "schemaVersion",
      "message": "{'schemaVersion': '1.2'} is not of type 'string'"
    }
  ]
}
Example #3:#
$ curl -X PATCH -H 'Content-Type:application/json-patch+json' -d '[{"op": "add", "path":"/schemaVersion", "value": "1.0" }]' "http://localhost:5000/api/records/77004d595c4940e991f410b9d82f54fa/draft?access_token=6MXcJvC74kF8Z7DSipBcZWko2D5iLQN5hjdt0MtAREqSUPlNtlhBppO30fcW"000/api/records/77004d595c4940e991f410b9d82f54fa/draft?access_token=6MXcJvC74kF8Z7DSipBcZWko2D5iLQN5hjdt0MtAREqSUPlNtlhBppO30fcW"
{
  "created": "2023-05-23T22:23:55.319451+00:00", 
  "id": "77004d595c4940e991f410b9d82f54fa", 
  "links": {
    "files": "http://localhost:5000/api/files/bc0d2e07-b331-4c33-8ff3-85e04c2972b3", 
    "publication": "http://localhost:5000/api/records/77004d595c4940e991f410b9d82f54fa", 
    "self": "http://localhost:5000/api/records/77004d595c4940e991f410b9d82f54fa/draft", 
    "versions": "http://localhost:5000/api/records/3bd707b7497e43eea6fb0706c8aabbe4/versions"
  }, 
  "metadata": {
    "$schema": "http://localhost:5000/api/communities/94a9567e-2fba-4677-8fde-a8b68bdb63e8/schemas/0#/draft_json_schema", 
    "Description": "A simple description", 
    "Instrument_Identifier": {
      "Identifier": "Test_Identifier_for_GWDG"
    }, 
    "Manufacturers": [
      {
        "manufacturerName": "GWDG"
      }, 
      {
        "manufacturerName": "Max Planck Society"
      }
    ], 
    "Name": "My dataset record", 
    "community": "94a9567e-2fba-4677-8fde-a8b68bdb63e8", 
    "open_access": true, 
    "owners": [
      3
    ], 
    "publication_state": "draft", 
    "schemaVersion": "1.0", 
    "title": "My dataset record"
  }, 
  "updated": "2023-05-24T20:09:59.800507+00:00"
}
Example #4:#
$ curl -X PATCH -H 'Content-Type:application/json-patch+json' -d '[{"op": "add", "path":"/Owner", "value": [ {"ownerName": "GWDG_and_max_planck" } ]}]' "http://localhost:5000/api/records/77004d595c4940e991f410b9d82f54fa/draft?access_token=6MXcJvC74kF8Z7DSipBcZWko2D5iLQN5hjdt0MtAREqSUPlNtlhBppO30fcW"
{
  "created": "2023-05-23T22:23:55.319451+00:00", 
  "id": "77004d595c4940e991f410b9d82f54fa", 
  "links": {
    "files": "http://localhost:5000/api/files/bc0d2e07-b331-4c33-8ff3-85e04c2972b3", 
    "publication": "http://localhost:5000/api/records/77004d595c4940e991f410b9d82f54fa", 
    "self": "http://localhost:5000/api/records/77004d595c4940e991f410b9d82f54fa/draft", 
    "versions": "http://localhost:5000/api/records/3bd707b7497e43eea6fb0706c8aabbe4/versions"
  }, 
  "metadata": {
    "$schema": "http://localhost:5000/api/communities/94a9567e-2fba-4677-8fde-a8b68bdb63e8/schemas/0#/draft_json_schema", 
    "Description": "A simple description", 
    "Instrument_Identifier": {
      "Identifier": "Test_Identifier_for_GWDG"
    }, 
    "LandingPage": "www.gwdg.de", 
    "Manufacturers": [
      {
        "manufacturerName": "GWDG"
      }, 
      {
        "manufacturerName": "Max Planck Society"
      }
    ], 
    "Name": "My dataset record", 
    "Owner": [
      {
        "ownerName": "GWDG_and_max_planck"
      }
    ], 
    "community": "94a9567e-2fba-4677-8fde-a8b68bdb63e8", 
    "open_access": true, 
    "owners": [
      3
    ], 
    "publication_state": "draft", 
    "schemaVersion": "1.0", 
    "title": "My dataset record"
  }, 
  "updated": "2023-05-24T20:15:52.105873+00:00"
}
Example #5:#
$ curl -X PATCH -H 'Content-Type:application/json-patch+json' -d '[{"op": "add", "path":"/LandingPage", "value": "www.gwdg.de" }]' "http://localhost:5000/api/records/77004d595c4940e991f410b9d82f54fa/draft?access_token=6MXcJvC74kF8Z7DSipBcZWko2D5iLQN5hjdt0MtAREqSUPlNtlhBppO30fcW"lhost:5000/api/records/77004d595c4940e991f410b9d82f54fa/draft?access_token=6MXcJvC74kF8Z7DSipBcZWko2D5iLQN5hjdt0MtAREqSUPlNtlhBppO30fcW"
{
  "created": "2023-05-23T22:23:55.319451+00:00", 
  "id": "77004d595c4940e991f410b9d82f54fa", 
  "links": {
    "files": "http://localhost:5000/api/files/bc0d2e07-b331-4c33-8ff3-85e04c2972b3", 
    "publication": "http://localhost:5000/api/records/77004d595c4940e991f410b9d82f54fa", 
    "self": "http://localhost:5000/api/records/77004d595c4940e991f410b9d82f54fa/draft", 
    "versions": "http://localhost:5000/api/records/3bd707b7497e43eea6fb0706c8aabbe4/versions"
  }, 
  "metadata": {
    "$schema": "http://localhost:5000/api/communities/94a9567e-2fba-4677-8fde-a8b68bdb63e8/schemas/0#/draft_json_schema", 
    "Description": "A simple description", 
    "LandingPage": "www.gwdg.de", 
    "Manufacturers": [
      {
        "manufacturerName": "GWDG"
      }, 
      {
        "manufacturerName": "Max Planck Society"
      }
    ], 
    "Name": "My dataset record", 
    "community": "94a9567e-2fba-4677-8fde-a8b68bdb63e8", 
    "open_access": true, 
    "owners": [
      3
    ], 
    "publication_state": "draft", 
    "schemaVersion": "1.0", 
    "title": "My dataset record"
  }, 
  "updated": "2023-05-24T20:10:55.352894+00:00"
}

Add externally referenced files to draft record:#

To add files that are located outside B2INST, a reference to that file can be added to a draft record object by defining a list of external references that include a file name and the corresponding EPIC PID. External references are added as normal metadata using a JSON Patch and can only be added during the draft stage.

HTTP method: PATCH
URL path: /api/records/RECORD_ID/draft
Required parameters: access_token
Payload data: the list of external references provided as a JSON Patch.
Status code on success: 200
Returns: informations about the updated metadata of the draft record
Notes:#

The external references must be proviced using EPIC PIDs and therefore you need to be able to register new PIDs with an EPIC PID hosting institute using a registered prefix. It is possible to get a prefix through EUDAT, please use the contact form for this.

Command:#
curl -X PATCH -H 'Accept:application/json-patch+json' -d '["op": "add", "path": "/external_pids", "value": "[{\"ePIC_PID\": \"prefix/suffix-of-file\", \"key\": \"filename\"},{\"ePIC_PID\": \"prefix/suffix-of-file-2\", \"key\": \"filename-2\"}]' "https://<B2INST_HOST>/api/records/<RECORD_ID>/draft?access_token=$ACCESS_TOKEN"

Submit draft record for publication:#

This action marks the draft record as complete and submits it for publication. Currently, B2INST automatically publishes all the submitted drafts. Please be advised that publishing the draft will make its files immutable.

A draft record is submitted for publication if a special metadata field, called ‘publication_state’ is set to ‘submitted’. This field can be set using the metadata update request described above.

Depending on the community specification, other fields could be required in order to successfully publish a record. In case one of the required fields is missing the request fails and an error message is returned with further details.

HTTP method: POST

URL path: /api/records/<RECORD_ID>/draft

Required parameters: access_token

Payload data: JSON Patch operation that alters the publication_state metadata field of the record metadata, see example below.

Status code on success: 200
Notes:#
  • This request is essentially a metadata update request as described above.
Command:#
curl -X PATCH -H 'Content-Type:application/json-patch+json' -d \
    '[{"op": "add", "path":"/publication_state", "value": "submitted"}]' \
    "https://<B2INST_HOST>/api/records/<RECORD_ID>/draft?access_token=<ACCESS_TOKEN>"
Example:#
$ curl -X PATCH -H 'Content-Type:application/json-patch+json' -d  '[{"op": "add", "path":"/publication_state", "value": "submitted"}]' "http://localhost:5000/api/records/77004d595c4940e991f410b9d82f54fa/draft?access_token=6MXcJvC74kF8Z7DSipBcZWko2D5iLQN5hjdt0MtAREqSUPlNtlhBppO30fcW"
{
  "created": "2023-05-23T22:23:55.319451+00:00", 
  "id": "77004d595c4940e991f410b9d82f54fa", 
  "links": {
    "files": "http://localhost:5000/api/files/bc0d2e07-b331-4c33-8ff3-85e04c2972b3", 
    "publication": "http://localhost:5000/api/records/77004d595c4940e991f410b9d82f54fa", 
    "self": "http://localhost:5000/api/records/77004d595c4940e991f410b9d82f54fa/draft", 
    "versions": "http://localhost:5000/api/records/3bd707b7497e43eea6fb0706c8aabbe4/versions"
  }, 
  "metadata": {
    "$schema": "http://localhost:5000/api/communities/94a9567e-2fba-4677-8fde-a8b68bdb63e8/schemas/0#/draft_json_schema", 
    "Description": "A simple description", 
    "Instrument_Identifier": {
      "Identifier": "GWDG_ePIC_test123", 
      "identifierType": "Test_Identifier_for_GWDG"
    }, 
    "LandingPage": "www.gwdg.de", 
    "Manufacturers": [
      {
        "manufacturerName": "GWDG"
      }, 
      {
        "manufacturerName": "Max Planck Society"
      }
    ], 
    "Name": "My dataset record", 
    "Owner": [
      {
        "ownerName": "GWDG_max_planck"
      }
    ], 
    "community": "94a9567e-2fba-4677-8fde-a8b68bdb63e8", 
    "ePIC_PID": "http://hdl.handle.net/21.T11975/B2INST_LOCAL/77004d595c4940e991f410b9d82f54fa", 
    "open_access": true, 
    "owners": [
      3
    ], 
    "publication_state": "published", 
    "schemaVersion": "1.0", 
    "title": "My dataset record"
  }, 
  "updated": "2023-05-24T20:17:20.268183+00:00"
}

Update published record metadata:#

This request updates the metadata of an already published record without creating a new version.

HTTP method: PATCH

URL path: /api/records/<RECORD_ID>/

Required parameters: access_token

Payload data: the metadata for the published record object to be updated, in the JSON Patch format (see http://jsonpatch.com/)

Status code on success: 200
Notes:#
  • The JSON Patch format contains one or more JSONPath strings. The root of these paths are the metadata object, as this is the only mutable object. For instance, to update the title field of the record, use this JSONPath: /titles/title

See the Update draft record metadata request for examples.

Record versioning#

The following requests concern the versioning of published records. Click on a title to show details. Create new version of published record

Create a new version of an existing published record into a new draft.#

HTTP method: GET

URL path: /api/records/<RECORD_HEAD_ID>/versions

Required parameters: None

Status code on success: 200

Returns: a JSON structure containing a list of all record versions with identifier, version number and URL.

Notes:#

  • The record head identifier is not the same as the record identifier. Use the metadata of the record to find the record head identifier, located in the JSONPath /links/versions.
  • If a record is not versioned, the result will be empty.

Command: 

curl -H "Content-Type:application/json" "https://<B2INST_HOST>/api/records/<RECORD_HEAD_ID>/versions"

Return Example:

On not found error:

Other requests#

The following requests are the remaining requests possible in B2INST. Click on a title to show details.

Report a record as an abuse record#

If there is anything wrong with the record users can report it as an abuse record. An email will be sent to the related admin, and it will be followed up. There are 4 different reasons listed on the report abuse form and the reporter should choose one of: - Abuse or Inappropriate content - Copyrighted material - Not research data - Illegal content

The reporter can also send a message to explain more about the problem. It is possible for an anonymous user to send the report and authentication is not required.

HTTP method: POST

URL path: /api/records/<RECORD_ID>/abuse

Required parameters: None

Payload data: JSON object with information about reporter, the reason indicated by booleans and a message.

Status code on success: 200

Returns: a message that an email was sent and the record is reported

Command:

Get record statistics#

Returns statistics of a record, indicated by statistic type.

Supported statistics:

bucket-file-download-total - total downloads per file in a bucket

More statistics might be added in future releases of B2INST.

HTTP method: POST

URL path: /api/stats

Required parameters: None

Payload data: JSON structure containing the statistic and required elements for that statistic, see below

Status code on success: 200

Returns: JSON structure containing requested statistics

Command:

Delete draft record#

Delete a draft record.

HTTP method: DELETE

URL path: /api/records/<RECORD_ID>/draft

Required parameters: access_token

Status code on success: 204

Returns: no contents.

Notes: you can only delete draft records that you own, not published records.

Command: 

curl -X DELETE "https://<B2INST_HOST>/api/records/<RECORD_ID>/draft?access_token=<ACCESS_TOKEN>"

Delete published record#

Delete a published record.

HTTP method: DELETE

URL path: /api/records/<RECORD_ID>

Required parameters: access_token

Status code on success: 204

Returns: no contents.

Notes: only a site administrator can delete a published record.
Command:#
curl -X DELETE "https://<B2INST_HOST>/api/records/<RECORD_ID>/?access_token=<ACCESS_TOKEN>"
Example:#
$ curl -X DELETE "https://localhost:5000/api/records/f6c354183899423a9425642fada29d72?access_token=6MXcJvC74kF8Z7DSipBcZWko2D5iLQN5hjdt0MtAREqSUPlNtlhBppO30fcW"
{
  "status": 410,
  "message": "PID has been deleted."
}

Support#

Hands-on material is available from the EUDAT Training Repository.

Our B2INST presentations offer training material for the service.

Support for B2INST and its REST API is available via the EUDAT ticketing system through the webform.

If you have comments on this page, please submit them through the EUDAT support request system.