REST API

IMPORTANT NOTE: this document describes the B2SHARE REST API at a point in time when the API is still in a development state. This document is currently also under development. What is said below might change. The API is planned to be production ready in December 2014. However, the API will also continue to be further developed after December 2014.

The B2SHARE HTTP REST API

The B2HARE HTTP REST API can be used for interacting with B2SHARE via external programs, for example for integrating with other web-sites, like e.g. research community portals, or for up- or downloading of large data sets that are not easily handled via a web browser. The REST API can also be used for metadata harvesting.

Using the API

The REST API is used by letting a program make requests by calling a URL via the standard HTTP protocol’s GET or POST methods.

Authentication

Only authenticated users can use the API. Authentication is made by passing an access token in the request. The access token is an encrypted string which can be created in the user profile when logged in to the B2SHARE web user interface. B2SHARE’s access tokens follow the OAuth 2.0 standard.

To get an access token, login to B2SHARE and click your username, then choose “Account” and then click “Applications” in the menu to the left.

Click on “New token”, enter a name and click “Create”:

This will create an access token, your access token is visible under “Access token” on the screen:

Please note that this is the only time the access token is visible, so copy it to a safe place. Then click “Save”. The access token is now ready for use. Access tokens can be deleted with the delete button for the particular token, which is found by clicking the token’s name in the menu “Applications”.

Making Requests

Requests are made by calling an URL with parameters as described below. Each URL consists of a base url and a path. One of the following base urls can be used for the current B2SHARE instance:

https://b2share.eudat.eu - the base url for the production site.

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

Note: during development are new versions of the API only available on the development server: https://test-eudatis.csc.fi

Each allowed request is described below as follows:

Description - A description of the function of the request.

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

HTTP method - whether the HTTP protocols GET or POST method is used.

Example - an example of usage using the program curl from the command line. “example.org” is used as a fictive base URL for the examples. Substitute “example.org” with a base URL from the list above.

Variables in the descriptions:

ACCESS_TOKEN - represents an access token created as described above (mandatory)

COMMUNITY_NAME - name of a user community in B2SHARE (optional)

PAGE_SIZE - size of page for pagination of output data (optional)

PAGE_OFFSET - page offset (page number) for paginated output data (optional)

RECORD_ID - identifier for a specific record

DEPOSITION_ID - identifier for a specific deposition

Note: A record is unchangeable and has a PID assigned to it. A user can create a record by first creating a deposition, which is modifiable. Files and metadata can be placed into a deposition, but not into a record.

List all the records

List all the records, without any filtering.

• HTTP method: GET
• URL path: /api/records
• Required parameters: access_token
• Optional parameters: page_size, page_offset

Example: curl -i http://example.org/api/records?access\_token=LKR35GP7TF&page_size=5&page_offset=2

List records per community

List all records of a specific community.

• URL path: /api/records/COMMUNITY_NAME
• HTTP method: GET
• Required parameters: access_token
• Optional parameters: page_size, page_offset
• Returns: the list of records (as json) or an error message with the list of valid community identifiers if the COMMUNITY_ID is wrong.

Example: curl -i http://example.org/api/records/BBMRI?access\_token=LKR35GP7TF&page_size=10&page_offset=3

List a specific record

List the metadata of the record specified by RECORD_ID

• URL path: /api/record/RECORD_ID
• HTTP method: GET
• Required parameters: access_token
• Optional parameters: [none]

Example: curl -i http://example.org/api/record/1?access\_token=LKR35GP7TF

Create a new deposition

Create a new deposition.

• URL path: /api/depositions
• HTTP method: POST
• Required parameters: access_token
• Returns: the URL of the deposition (both as json and in the Location header)

Example: curl -i -X POST http://example.org/api/depositions?access\_token=LKR35GP7TF

Location: http:// .../api/deposition/23k85hjfiu2y346

Upload a new file into a deposition object

Upload a new file into a deposition object

• URL path: /api/deposition/DEPOSITION_ID/files
• Http Method: POST

Example: curl -i http://example.org/api/deposit/57?access\_token=LKR35GP7TF

Responses

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

A deposition is represented as a JSON object: { "field1": value, … }

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

[{ "field1": value, ... }, … ]

Timestamps are in UTC and formatted according to ISO 8601:

YYYY-MM-DDTHH:MM:SS+00:00

Response Fields

Field name	JSON data type	Description
recordID	Number	The depositions’s unique ID number
authors	String	Creator’s full name (comma separated if more than one)
title	String	Name of the deposition
description	String	Description of the deposition
domain	String	Scientific domain
date	String	Deposit date
pid	String	The persistent identifier for the deposition
email	String	Depositor’s e-mail
file_url	String	URL(s) to the deposited file(s)
licence	String	License type for the deposit
files	Object Array	Deposited file’s/files’: [{"full_name": file name with extension (String), "url": relative url path to file (String), "size": size of the file (Number)}]