REST API

This page is deprecated! Go to the B2SHARE HTTP REST API help page for more information

---

The B2SHARE HTTP REST API

This page is a draft for the B2SHARE 2.0 version of the HTTP REST API. The page shows work in progress and can be updated at any time.

Authentication

As before?

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 (in JSON format) or an error message with the list of valid community identifiers if the COMMUNITY_ID is invalid.

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

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 field 'Location' in the http header)

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

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
• Required input data: the file, sent as multipart/form-data
• Required parameters: access_token
• Returns: the name and size of the newly uploaded file

Example: curl -i -X POST -F [email protected] http://example.org/api/deposition/23k85hjfiu2y346/files?access\_token=LKR35GP7TF

List the files uploaded into a deposition object

List the files uploaded into a deposition object

• URL path: /api/deposition/DEPOSITION_ID/files
• Http Method: GET
• Required parameters: access_token
• Returns: the name and size of all the files in the deposition object

Example: curl -i http://example.org/api/deposition/23k85hjfiu2y346/files?access\_token=LKR35GP7TF

Commit deposition

This action transforms a deposition into an immutable record.

• URL path: /api/deposition/DEPOSITION_ID/commit
• HTTP Method: POST
• Required input data: the metadata for the record object to be created. This metadata must be sent as a list of fields (key:value pairs). The required fields are:
  • domain [string]: the id of the community to which the record belongs
  • open_access [boolean]: the access restriction of the new record
  • title [string]: the title of the new record
  • description [string]: the description of the new record

Depending on the domain specification, other fields could be required in order to make a successful commit. The list of all the fields, with their description, multiplicity and controlled vocabulary, is automatically returned to the user in case one of the required fields is missing.

• Required parameters: access_token
• Returns: the location URL of the new record if the submitted metadata is valid; otherwise, the list of all the metadata fields that can be filled in and details on each one.

Example: curl -i -X POST -H "Content-Type: application/json" -d '{"domain":"generic", "title":"REST Test Title", "description":"REST Test Description", "open_access":"true"}' http://.../api/deposition/DEPOSITION_ID/commit?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
record_id	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)}]