Successfully reported this slideshow.
We use your LinkedIn profile and activity data to personalize ads and to show you more relevant ads. You can change your ad preferences anytime.
Store and Publish Research Data
b2share.eudat.eu
www.eudat.euEUDAT receives funding from the European Union's Horizon 2020...
b2share.eudat.eu
B2SHARE is...
… a user-friendly, reliable and
trustworthy way for researchers,
scientific communities and...
b2share.eudat.eu
What is the B2SHARE REST API?
The B2SHARE REST API is a set of instructions to interact
with a B2SHARE se...
b2share.eudat.eu
What can I do with the B2SHARE
API?
List all existing records and communities
Search for specific records...
b2share.eudat.eu
What is an API?
An Application Programming Interface (API) is a
specification of a set of definitions, pr...
b2share.eudat.eu
HTTP requests
A specific call to a service through an API using a HTTP
request method with address and pa...
b2share.eudat.eu
HTTP requests (2)
Several HTTP request methods possible, e.g.:
GET: get data of specified resource
POST: ...
b2share.eudat.eu
Making a request
Requests can be made by using a specific application
directly (e.g. a browser) or by usi...
b2share.eudat.eu
Making a request
10
Browser CLI tool
Your app or
workflow
HTTP response:
- Header
- Status code
- Respons...
b2share.eudat.eu
Important concepts of B2SHARE
Communities:
Curate datasets which are part of the scientific domain or a
r...
b2share.eudat.eu
B2SHARE request variables
B2SHARE defines several request variables that
function as identifiers for obje...
b2share.eudat.eu
Community metadata schemas
Every community defines its own metadata schema
Metadata schemas:
Contain desc...
b2share.eudat.eu
Adding metadata
Metadata is added to a record using the API:
Upon creation of a draft record
Or by provid...
b2share.eudat.eu
Adding files
Files can be added during the draft phase of your new
record using a PUT request
Files are u...
b2share.eudat.eu
Publishing your draft record
Draft records are published by altering the value of the
publication state i...
b2share.eudat.eu
Authentication through the API
B2SHARE does not accept username and password
combination, instead use tok...
b2share.eudat.eu
Getting your access token
Log in on B2SHARE and navigate to profile page:
Create a token by entering a ne...
b2share.eudat.eu
Simple examples (1)
Protocol and host: https://trng-b2share.eudat.eu
Application: curl (using command-lin...
b2share.eudat.eu
Simple examples (2)
Get a specific record:
List all your draft records:
Access token required!
List files...
b2share.eudat.eu
Full publication workflow
Publishing in B2SHARE using the API involves multiple
steps:
Identify a target ...
b2share.eudat.eu
Full publication workflow diagram
22
Create
draft
Add metadata
Add files
POST /api/records
GET /api/recor...
b2share.eudat.eu
For more info: https://eudat.eu/services/b2share
B2SHARE User Documentation:
https://eudat.eu/services/us...
www.eudat.eu
This work is licensed under the Creative Commons CC-BY 4.0 licence
EUDAT receives funding from the European U...
Upcoming SlideShare
Loading in …5
×

B2SHARE REST API - New ppt available at https://www.slideshare.net/EUDAT/eudat-b2share-api-how-to-store-and-publish-research-data-using-the-b2share-api

459 views

Published on

EUDAT B2SHARE API Presentation: How to store and publish research data using the B2SHARE API.

Published in: Data & Analytics
  • Be the first to comment

  • Be the first to like this

B2SHARE REST API - New ppt available at https://www.slideshare.net/EUDAT/eudat-b2share-api-how-to-store-and-publish-research-data-using-the-b2share-api

  1. 1. Store and Publish Research Data b2share.eudat.eu www.eudat.euEUDAT receives funding from the European Union's Horizon 2020 programme - DG CONNECT e-Infrastructures. Contract No. 654065 B2SHARE REST API How to store and publish research data using the B2SHARE REST API This work is licensed under the Creative Commons CC-BY 4.0 licence Version 1 June 2017
  2. 2. b2share.eudat.eu B2SHARE is... … a user-friendly, reliable and trustworthy way for researchers, scientific communities and scientists to store and publish research data from diverse contexts 2
  3. 3. b2share.eudat.eu What is the B2SHARE REST API? The B2SHARE REST API is a set of instructions to interact with a B2SHARE service instance The B2SHARE REST API: Provides direct remote interaction with the service without using a graphical user interface Allows integration within application or data processing workflows for automation of publishing tasks Supports any programming language or operating system that supports HTTP requests There is no limitation on usage and number of calls, even for unregistered users To create new or modify existing content, registration is required 4
  4. 4. b2share.eudat.eu What can I do with the B2SHARE API? List all existing records and communities Search for specific records and communities Retrieval of community-specific information Including community metadata schemas Create new draft records Upload files to draft records Add metadata using metadata schemas Publish draft records Modification of the metadata of existing records 5
  5. 5. b2share.eudat.eu What is an API? An Application Programming Interface (API) is a specification of a set of definitions, protocols and tools to interact with a service, possibly from a remote location Provides an abstraction of the underlying service technologies used by the service itself and external applications HTTP requests return machine-readable structures of data representing the current state of a piece of information, or after altering it on request Returned data is provided in specific formats like XML or JSON Any browser is using requests in order to get information from a server and to present it to the user 6
  6. 6. b2share.eudat.eu HTTP requests A specific call to a service through an API using a HTTP request method with address and parameters An address is a URL with optionally additional parameters: URL = protocol + hostname + port + path Protocol: always http:// or https:// Hostname: base address, e.g. b2share.eudat.eu Port: sometimes required specifically, usually 80 Path: endpoint specification, e.g. api/record/1 Parameters are additional options given to the request Every request returns a HTTP status code and response text, even when an error occurred On success the current state of the requested piece of information is provided 7
  7. 7. b2share.eudat.eu HTTP requests (2) Several HTTP request methods possible, e.g.: GET: get data of specified resource POST: submit data to be processed for specified resource PUT: upload representation of URI (e.g. file) PATCH: modify (meta)data of specified source For different operations, use different methods The B2SHARE service accepts payloads along with a HTTP request, e.g. text, binary data, files 8
  8. 8. b2share.eudat.eu Making a request Requests can be made by using a specific application directly (e.g. a browser) or by using a programming language that supports making requests in code Example applications: GUI: any file transfer application or web interface Command line: cURL, wGet Almost all programming languages support making requests over HTTP For more complex operations (like publication), a dedicated interface or command line application is required 9
  9. 9. b2share.eudat.eu Making a request 10 Browser CLI tool Your app or workflow HTTP response: - Header - Status code - Response text HTTP request: - Request method - Header - URI & parameters - Authentication - Payloads Server Client
  10. 10. b2share.eudat.eu Important concepts of B2SHARE Communities: Curate datasets which are part of the scientific domain or a research project Maintain their own metadata schemas and have community administrators Records: Contain data files and associated metadata Connected to a community which maintains it Metadata: Set of common fixed metadata fields and custom metadata blocks with additional fields Governed by fixed and community metadata schemas States: Current condition of a record, either draft, submitted or published Can be changed through the API 11
  11. 11. b2share.eudat.eu B2SHARE request variables B2SHARE defines several request variables that function as identifiers for objects in B2SHARE Used in most HTTP request addresses as part of the path to access specific objects directly Most important variables: COMMUNITY_ID: identifier of a user community RECORD_ID: identifier for a specific record, in either state FILE_BUCKET_ID: identifier for a set of files of a specific record 12
  12. 12. b2share.eudat.eu Community metadata schemas Every community defines its own metadata schema Metadata schemas: Contain descriptions, vocabularies and expected structure and format of every metadata field Define which fields are mandatory to fill in Definitions are publically available 13
  13. 13. b2share.eudat.eu Adding metadata Metadata is added to a record using the API: Upon creation of a draft record Or by providing so-called JSON patches in a request Patches modify the current state of the metadata by either changing, adding or removing fields and values The structure of the data provided in the patch request must strictly follow the metadata schema of the community As many patches as necessary can be applied before publishing your draft record 14 Add metadata Draft record
  14. 14. b2share.eudat.eu Adding files Files can be added during the draft phase of your new record using a PUT request Files are uploaded into the file bucket of the draft record, not the draft record itself Use the file bucket ID found in the metadata of the draft record Files are uploaded one-by-one in separate requests As many file upload requests as necessary can be made before publishing your draft record 15 Add files Draft record
  15. 15. b2share.eudat.eu Publishing your draft record Draft records are published by altering the value of the publication state in the metadata Once your record is published: The included files can not be changed anymore! No new files can be added! Metadata can be changed after publication, but will create a new version of your published record Persistent identifiers are automatically added 16 Commit Draft record Published record
  16. 16. b2share.eudat.eu Authentication through the API B2SHARE does not accept username and password combination, instead use tokens for authentication! B2SHARE contains open and restricted data: Public: all published records and metadata, most files No access token required Private: your draft records and files in private records Only accessible using your access token as parameter in HTTP request Access tokens: Automatically generated unique string of characters attached to your account in B2SHARE Unlimited number of tokens can be generated Only known by the owner, do not share with others! 17
  17. 17. b2share.eudat.eu Getting your access token Log in on B2SHARE and navigate to profile page: Create a token by entering a new name: Click on ‘New token’ Note: the token will only be shown once, so store it safely!
  18. 18. b2share.eudat.eu Simple examples (1) Protocol and host: https://trng-b2share.eudat.eu Application: curl (using command-line interface) HTTP method: GET Retrieve all existing records: List all communities: Search for specific records of a community: 19 curl –X GET https://trng-b2share.eudat.eu/api/records curl –X GET https://trng-b2share.eudat.eu/api/records? q=community:COMMUNITY_ID curl –X GET https://trng-b2share.eudat.eu/api/communities
  19. 19. b2share.eudat.eu Simple examples (2) Get a specific record: List all your draft records: Access token required! List files of specific record: FILE_BUCKET_ID required! 20 curl –X GET https://trng-b2share.eudat.eu/api/records/RECORD_ID curl –X GET https://trng-b2share.eudat.eu/api/files/ FILE_BUCKET_ID curl –X GET https://trng-b2share.eudat.eu/api/records? drafts=1&access_token=ACCESS_TOKEN
  20. 20. b2share.eudat.eu Full publication workflow Publishing in B2SHARE using the API involves multiple steps: Identify a target community for your data Retrieve the metadata schema definition of the community The submitted metadata will have to conform to this schema Create a draft record: Upload files into the draft record (one by one) Add metadata according to schema (possibly in multiple steps) Publish the record 21
  21. 21. b2share.eudat.eu Full publication workflow diagram 22 Create draft Add metadata Add files POST /api/records GET /api/records/RECORD_ID/draft PATCH /api/records/RECORD_ID/draft PUT /api/records/FILE_BUCKET_ID/FILE_NAME Commit Published record PATCH /api/records/RECORD_ID/draft Draft record PID Checksum Needs approval? Submitted record Community Approve NO YES
  22. 22. b2share.eudat.eu For more info: https://eudat.eu/services/b2share B2SHARE User Documentation: https://eudat.eu/services/userdoc/b2share B2SHARE Training presentations: https://www.eudat.eu/b2share-training-suite B2SHARE hands-on training: https://github.com/EUDAT-Training/B2SHARE-Training 23
  23. 23. www.eudat.eu This work is licensed under the Creative Commons CC-BY 4.0 licence EUDAT receives funding from the European Union's Horizon 2020 programme - DG CONNECT e-Infrastructures. Contract No. 654065 Authors Contributors Hans van Piggelen, SURFsara Thank you!

×