-
Notifications
You must be signed in to change notification settings - Fork 32
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 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.
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.
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”.
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:
- the base url for the production site.
- 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 deposition
Description: List all depositions for a specific community (and accessible for the authenticated user).
URL suffixes:
/api/depositions/COMMUNITY_NAME?access_token=ACCESS_TOKEN
/api/depositions/COMMUNITY_NAME/PAGE_SIZE?access_token=ACCESS_TOKEN
/api/depositions/COMMUNITY_NAME/PAGE_SIZE/PAGE_OFFSET?access_token=ACCESS_TOKEN
HTTP method: GET
Example: curl -i http://example.org/api/depositions/BBMRI/2/3?access\_token=LKR35GP7TF
Description: List all depositions (which are accessible for the authenticated user)
URL suffixes:
/api/depositions?access_token=ACCESS_TOKEN
/api/depositions/PAGE_SIZE?access_token=ACCESS_TOKEN
/api/depositions/PAGE_SIZE/PAGE_OFFSET?access_token=ACCESS_TOKEN
Http Method: GET
Example: curl -i http://example.org/api/depositions?access\_token=LKR35GP7TF
Description: Retrieve information about requested record
URL suffix: /api/deposit/RECORD_ID?access_token=ACCESS_TOKEN
Http Method: GET
Example: curl -i http://example.org/api/deposit/57?access\_token=LKR35GP7TF
Description: Deposit (a collection of) deposition(s) (for a specific community) for the currently authenticated user
URL path: under development
Http Method: POST
Example: TBD
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
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 |
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)} |