-
Notifications
You must be signed in to change notification settings - Fork 33
REST API
This is now a draft for the B2SHARE 2.0 version of the HTTP REST API.
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)}] |