-
Notifications
You must be signed in to change notification settings - Fork 32
REST API
This page is deprecated! Go to the B2SHARE HTTP REST API help page for more information
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.
As before?
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, 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 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 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.
- 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
- 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
- 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
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
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 |
---|---|---|
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 |
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)}] |