This training module provides training material and in-depth information in using the EUDAT B2SHARE service through application programming interfaces (APIs). It covers complete usage and implementation of the B2SHARE REST API and provides step-by-step examples using Python 3. All functionality is also available in the web interface of B2SHARE, but the API allows integration of its functionality into your own workflows and applications.
All submodules have been set up to use the B2SHARE training instance, which you can freely try and experiment with.
Note: Only use the training instance for your testing and scripts. If you are ready for actual publication, switch to the production instance of B2SHARE.
Please note that in order to use some functionality of the services you need to register your account and log in. Click here to do so.
Although this module is complete, it is subject to change due to possible future alterations in the API specification. As soon as there are updates, this training module will be updated as well. In the meantime, you can check out the currently up-to-date API implementation on the B2SHARE website.
This training modules assumes you have knowledge about data management basics such as depositing, metadata and persistent identifiers. In addition, all scripts are written in the Python 3 language. If you have no experience in programming or want to learn more about Python, it is highly recommended to follow some tutorials or start reading about it. General information can be found in the latest Python 3 documentation.
For trainees who do not have the possibility to install Python and the required Python packages, EUDAT provides pre-installed virtual machines in a training environment. To get access to this training environment, please use the EUDAT contact pages. Please provide some details on which community you are from and in which context you would like to follow the tutorial.
The B2SHARE service makes a distinction between the two terms record and draft record. A record is published and therefore unchangeable and has persistent identifiers (PID) assigned to it, as well as checksums. For clarity, often a record will be referred to as a published record.
A user can create a record by first creating a draft record, which is modifiable. Files can be placed into a draft record, but not into a published record. If you update the files of the draft equivalent of the published record, a new version of that record will be created with new persistent identifiers and storage locations.
In practice, a published record is equivalent to a draft record when solely trying to read a record through the service API. Metadata of an existing published record can be updated by modifying the corresponding draft record and committing it as a new version of the original record.
Note: it it highly recommended to follow the guides in the given order. Later modules assume specific knowledge about Python and how to setup requests.
| Submodule | Contents |
|---|---|
| Introduction | General introduction to publishing data in B2SHARE |
| Getting your API token | Information on registration and creating your API access tokens for usage with the Python scripts |
| Retrieve record details | Learn how to get record information of specific existing records |
| List existing records | Retrieve listings of records and paginate them |
| Communities | Community-specific functionality is explained |
| Create new record | Learn how to create new records and add files and metadata |
| Update record metadata | Learn how to update the metadata of existing records |
| Update all community metadata fields | Learn how to update all community metadata fields in your record |
| Record versioning | Learn how to update the files in a record and thereby creating a new version of that record |
| Special requests | Various examples of special requests made using the API |
| Appendix A | Setup and install guide for Python |
| Appendix B | Reference guide for API requests and record metadata |
| Appendix C | Example script with functions handling B2SHARE records |
To quickly get an overview of the requests you can make with the B2SHARE service, see the Request and Metadata Reference Guide appendix.
If you encounter any problems or have any remarks, please contact EUDAT through the website contact form or request support directly.