HTTP REST API - EUDAT Documentation

<!doctype html> <html lang="en" class="no-js"> <head> <meta charset="utf-8"> <meta name="viewport" content="width=device-width,initial-scale=1"> <link rel="canonical" href="https://docs.eudat.eu/b2share/httpapi/"> <link rel="prev" href="../cli/"> <link rel="next" href="../faq/"> <link rel="icon" href="../../assets/images/favicon.png"> <meta name="generator" content="mkdocs-1.6.1, mkdocs-material-9.6.3"> <title>HTTP REST API - EUDAT Documentation</title> <link rel="stylesheet" href="../../assets/stylesheets/main.d7758b05.min.css"> <link rel="stylesheet" href="../../assets/stylesheets/palette.06af60db.min.css"> <link rel="preconnect" href="https://fonts.gstatic.com" crossorigin> <link rel="stylesheet" href="https://fonts.googleapis.com/css?family=Roboto:300,300i,400,400i,700,700i%7CRoboto+Mono:400,400i,700,700i&display=fallback"> <style>:root{--md-text-font:"Roboto";--md-code-font:"Roboto Mono"}</style> <link rel="stylesheet" href="../../config/extra.css"> <script>__md_scope=new URL("../..",location),__md_hash=e=>[...e].reduce(((e,_)=>(e<<5)-e+_.charCodeAt(0)),0),__md_get=(e,_=localStorage,t=__md_scope)=>JSON.parse(_.getItem(t.pathname+"."+e)),__md_set=(e,_,t=localStorage,a=__md_scope)=>{try{t.setItem(a.pathname+"."+e,JSON.stringify(_))}catch(e){}}</script> </head> <body dir="ltr" data-md-color-scheme="default" data-md-color-primary="indigo" data-md-color-accent="indigo"> <input class="md-toggle" data-md-toggle="drawer" type="checkbox" id="__drawer" autocomplete="off"> <input class="md-toggle" data-md-toggle="search" type="checkbox" id="__search" autocomplete="off"> <label class="md-overlay" for="__drawer"></label> <div data-md-component="skip"> <a href="#eudat-b2share-http-rest-api" class="md-skip"> Skip to content </a> </div> <div data-md-component="announce"> </div> <header class="md-header" data-md-component="header"> <nav class="md-header__inner md-grid" aria-label="Header"> <a href="../.." title="EUDAT Documentation" class="md-header__button md-logo" aria-label="EUDAT Documentation" data-md-component="logo"> <img src="../../images/EUDAT_Partial_White.png" alt="logo"> </a> <label class="md-header__button md-icon" for="__drawer"> <svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 24 24"><path d="M3 6h18v2H3zm0 5h18v2H3zm0 5h18v2H3z"/></svg> </label> <div class="md-header__title" data-md-component="header-title"> <div class="md-header__ellipsis"> <div class="md-header__topic"> EUDAT Documentation </div> <div class="md-header__topic" data-md-component="header-topic"> HTTP REST API </div> </div> </div> <form class="md-header__option" data-md-component="palette"> <input class="md-option" data-md-color-media="" data-md-color-scheme="default" data-md-color-primary="indigo" data-md-color-accent="indigo" aria-label="Switch to dark mode" type="radio" name="__palette" id="__palette_0"> <label class="md-header__button md-icon" title="Switch to dark mode" for="__palette_1" hidden> <svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 24 24"><path d="M12 2a7 7 0 0 0-7 7c0 2.38 1.19 4.47 3 5.74V17a1 1 0 0 0 1 1h6a1 1 0 0 0 1-1v-2.26c1.81-1.27 3-3.36 3-5.74a7 7 0 0 0-7-7M9 21a1 1 0 0 0 1 1h4a1 1 0 0 0 1-1v-1H9z"/></svg> </label> <input class="md-option" data-md-color-media="" data-md-color-scheme="slate" data-md-color-primary="indigo" data-md-color-accent="indigo" aria-label="Switch to light mode" type="radio" name="__palette" id="__palette_1"> <label class="md-header__button md-icon" title="Switch to light mode" for="__palette_0" hidden> <svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 24 24"><path d="M12 2a7 7 0 0 1 7 7c0 2.38-1.19 4.47-3 5.74V17a1 1 0 0 1-1 1H9a1 1 0 0 1-1-1v-2.26C6.19 13.47 5 11.38 5 9a7 7 0 0 1 7-7M9 21v-1h6v1a1 1 0 0 1-1 1h-4a1 1 0 0 1-1-1m3-17a5 5 0 0 0-5 5c0 2.05 1.23 3.81 3 4.58V16h4v-2.42c1.77-.77 3-2.53 3-4.58a5 5 0 0 0-5-5"/></svg> </label> </form> <script>var palette=__md_get("__palette");if(palette&&palette.color){if("(prefers-color-scheme)"===palette.color.media){var media=matchMedia("(prefers-color-scheme: light)"),input=document.querySelector(media.matches?"[data-md-color-media='(prefers-color-scheme: light)']":"[data-md-color-media='(prefers-color-scheme: dark)']");palette.color.media=input.getAttribute("data-md-color-media"),palette.color.scheme=input.getAttribute("data-md-color-scheme"),palette.color.primary=input.getAttribute("data-md-color-primary"),palette.color.accent=input.getAttribute("data-md-color-accent")}for(var[key,value]of Object.entries(palette.color))document.body.setAttribute("data-md-color-"+key,value)}</script> <label class="md-header__button md-icon" for="__search"> <svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 24 24"><path d="M9.5 3A6.5 6.5 0 0 1 16 9.5c0 1.61-.59 3.09-1.56 4.23l.27.27h.79l5 5-1.5 1.5-5-5v-.79l-.27-.27A6.52 6.52 0 0 1 9.5 16 6.5 6.5 0 0 1 3 9.5 6.5 6.5 0 0 1 9.5 3m0 2C7 5 5 7 5 9.5S7 14 9.5 14 14 12 14 9.5 12 5 9.5 5"/></svg> </label> <div class="md-search" data-md-component="search" role="dialog"> <label class="md-search__overlay" for="__search"></label> <div class="md-search__inner" role="search"> <form class="md-search__form" name="search"> <input type="text" class="md-search__input" name="query" aria-label="Search" placeholder="Search" autocapitalize="off" autocorrect="off" autocomplete="off" spellcheck="false" data-md-component="search-query" required> <label class="md-search__icon md-icon" for="__search"> <svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 24 24"><path d="M9.5 3A6.5 6.5 0 0 1 16 9.5c0 1.61-.59 3.09-1.56 4.23l.27.27h.79l5 5-1.5 1.5-5-5v-.79l-.27-.27A6.52 6.52 0 0 1 9.5 16 6.5 6.5 0 0 1 3 9.5 6.5 6.5 0 0 1 9.5 3m0 2C7 5 5 7 5 9.5S7 14 9.5 14 14 12 14 9.5 12 5 9.5 5"/></svg> <svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 24 24"><path d="M20 11v2H8l5.5 5.5-1.42 1.42L4.16 12l7.92-7.92L13.5 5.5 8 11z"/></svg> </label> <nav class="md-search__options" aria-label="Search"> <button type="reset" class="md-search__icon md-icon" title="Clear" aria-label="Clear" tabindex="-1"> <svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 24 24"><path d="M19 6.41 17.59 5 12 10.59 6.41 5 5 6.41 10.59 12 5 17.59 6.41 19 12 13.41 17.59 19 19 17.59 13.41 12z"/></svg> </button> </nav> <div class="md-search__suggest" data-md-component="search-suggest"></div> </form> <div class="md-search__output"> <div class="md-search__scrollwrap" tabindex="0" data-md-scrollfix> <div class="md-search-result" data-md-component="search-result"> <div class="md-search-result__meta"> Initializing search </div> <ol class="md-search-result__list" role="presentation"></ol> </div> </div> </div> </div> </div> </nav> </header> <div class="md-container" data-md-component="container"> <nav class="md-tabs" aria-label="Tabs" data-md-component="tabs"> <div class="md-grid"> <ul class="md-tabs__list"> <li class="md-tabs__item"> <a href="../.." class="md-tabs__link"> Documentation </a> </li> <li class="md-tabs__item"> <a href="../../b2access/" class="md-tabs__link"> B2ACCESS </a> </li> <li class="md-tabs__item"> <a href="../../b2drop/" class="md-tabs__link"> B2DROP </a> </li> <li class="md-tabs__item"> <a href="../../b2find/" class="md-tabs__link"> B2FIND </a> </li> <li class="md-tabs__item"> <a href="../../b2handle/" class="md-tabs__link"> B2HANDLE </a> </li> <li class="md-tabs__item"> <a href="../../b2inst/" class="md-tabs__link"> B2INST </a> </li> <li class="md-tabs__item"> <a href="../../b2safe/" class="md-tabs__link"> B2SAFE </a> </li> <li class="md-tabs__item md-tabs__item--active"> <a href="../overview/" class="md-tabs__link"> B2SHARE </a> </li> <li class="md-tabs__item"> <a href="../../datacite/" class="md-tabs__link"> DataCite </a> </li> <li class="md-tabs__item"> <a href="https://eudat.eu" class="md-tabs__link"> EUDAT website </a> </li> <li class="md-tabs__item"> <a href="https://eudat.eu/contact-support-request" class="md-tabs__link"> Feedback + Support </a> </li> </ul> </div> </nav> <main class="md-main" data-md-component="main"> <div class="md-main__inner md-grid"> <div class="md-sidebar md-sidebar--primary" data-md-component="sidebar" data-md-type="navigation" > <div class="md-sidebar__scrollwrap"> <div class="md-sidebar__inner"> <nav class="md-nav md-nav--primary md-nav--lifted md-nav--integrated" aria-label="Navigation" data-md-level="0"> <label class="md-nav__title" for="__drawer"> <a href="../.." title="EUDAT Documentation" class="md-nav__button md-logo" aria-label="EUDAT Documentation" data-md-component="logo"> <img src="../../images/EUDAT_Partial_White.png" alt="logo"> </a> EUDAT Documentation </label> <ul class="md-nav__list" data-md-scrollfix> <li class="md-nav__item"> <a href="../.." class="md-nav__link"> Documentation </a> </li> <li class="md-nav__item md-nav__item--nested"> <input class="md-nav__toggle md-toggle " type="checkbox" id="__nav_2" > <label class="md-nav__link" for="__nav_2" id="__nav_2_label" tabindex="0"> B2ACCESS </label> <nav class="md-nav" data-md-level="1" aria-labelledby="__nav_2_label" aria-expanded="false"> <label class="md-nav__title" for="__nav_2"> B2ACCESS </label> <ul class="md-nav__list" data-md-scrollfix> <li class="md-nav__item"> <a href="../../b2access/" class="md-nav__link"> Overview </a> </li> <li class="md-nav__item"> <a href="../../b2access/assurance/" class="md-nav__link"> Assurance </a> </li> <li class="md-nav__item"> <a href="../../b2access/concepts/" class="md-nav__link"> Concepts </a> </li> <li class="md-nav__item md-nav__item--nested"> <input class="md-nav__toggle md-toggle " type="checkbox" id="__nav_2_4" > <label class="md-nav__link" for="__nav_2_4" id="__nav_2_4_label" tabindex="0"> For Users </label> <nav class="md-nav" data-md-level="2" aria-labelledby="__nav_2_4_label" aria-expanded="false"> <label class="md-nav__title" for="__nav_2_4"> For Users </label> <ul class="md-nav__list" data-md-scrollfix> <li class="md-nav__item"> <a href="../../b2access/howto-mfa/" class="md-nav__link"> Enabling MFA </a> </li> <li class="md-nav__item"> <a href="../../b2access/howto-update-email/" class="md-nav__link"> Updating Email </a> </li> <li class="md-nav__item"> <a href="../../b2access/list-of-connected-organisations/" class="md-nav__link"> List of connected organisations </a> </li> <li class="md-nav__item md-nav__item--nested"> <input class="md-nav__toggle md-toggle " type="checkbox" id="__nav_2_4_4" > <label class="md-nav__link" for="__nav_2_4_4" id="__nav_2_4_4_label" tabindex="0"> For group administrators </label> <nav class="md-nav" data-md-level="3" aria-labelledby="__nav_2_4_4_label" aria-expanded="false"> <label class="md-nav__title" for="__nav_2_4_4"> For group administrators </label> <ul class="md-nav__list" data-md-scrollfix> <li class="md-nav__item"> <a href="../../b2access/howto-vos/" class="md-nav__link"> Requesting a group </a> </li> <li class="md-nav__item"> <a href="../../b2access/howto-vo-management/" class="md-nav__link"> Managing a group </a> </li> </ul> </nav> </li> <li class="md-nav__item md-nav__item--nested"> <input class="md-nav__toggle md-toggle " type="checkbox" id="__nav_2_4_5" > <label class="md-nav__link" for="__nav_2_4_5" id="__nav_2_4_5_label" tabindex="0"> For Service Providers </label> <nav class="md-nav" data-md-level="3" aria-labelledby="__nav_2_4_5_label" aria-expanded="false"> <label class="md-nav__title" for="__nav_2_4_5"> For Service Providers </label> <ul class="md-nav__list" data-md-scrollfix> <li class="md-nav__item"> <a href="../../b2access/howto-services/" class="md-nav__link"> Registering a services </a> </li> <li class="md-nav__item"> <a href="../../b2access/attributes-sp/" class="md-nav__link"> Available attributes </a> </li> </ul> </nav> </li> <li class="md-nav__item md-nav__item--nested"> <input class="md-nav__toggle md-toggle " type="checkbox" id="__nav_2_4_6" > <label class="md-nav__link" for="__nav_2_4_6" id="__nav_2_4_6_label" tabindex="0"> For Identity Providers </label> <nav class="md-nav" data-md-level="3" aria-labelledby="__nav_2_4_6_label" aria-expanded="false"> <label class="md-nav__title" for="__nav_2_4_6"> For Identity Providers </label> <ul class="md-nav__list" data-md-scrollfix> <li class="md-nav__item"> <a href="../../b2access/howto-idps/" class="md-nav__link"> Joining as an Identity Provider </a> </li> <li class="md-nav__item"> <a href="../../b2access/attributes-idp/" class="md-nav__link"> Consumed attributes </a> </li> </ul> </nav> </li> </ul> </nav> </li> <li class="md-nav__item"> <a href="../../b2access/about/" class="md-nav__link"> About </a> </li> </ul> </nav> </li> <li class="md-nav__item md-nav__item--nested"> <input class="md-nav__toggle md-toggle " type="checkbox" id="__nav_3" > <label class="md-nav__link" for="__nav_3" id="__nav_3_label" tabindex="0"> B2DROP </label> <nav class="md-nav" data-md-level="1" aria-labelledby="__nav_3_label" aria-expanded="false"> <label class="md-nav__title" for="__nav_3"> B2DROP </label> <ul class="md-nav__list" data-md-scrollfix> <li class="md-nav__item"> <a href="../../b2drop/" class="md-nav__link"> Overview </a> </li> <li class="md-nav__item md-nav__item--nested"> <input class="md-nav__toggle md-toggle " type="checkbox" id="__nav_3_2" > <label class="md-nav__link" for="__nav_3_2" id="__nav_3_2_label" tabindex="0"> For Users </label> <nav class="md-nav" data-md-level="2" aria-labelledby="__nav_3_2_label" aria-expanded="false"> <label class="md-nav__title" for="__nav_3_2"> For Users </label> <ul class="md-nav__list" data-md-scrollfix> <li class="md-nav__item"> <a href="../../b2drop/user/" class="md-nav__link"> Overview </a> </li> <li class="md-nav__item md-nav__item--nested"> <input class="md-nav__toggle md-toggle " type="checkbox" id="__nav_3_2_2" > <label class="md-nav__link" for="__nav_3_2_2" id="__nav_3_2_2_label" tabindex="0"> For groups </label> <nav class="md-nav" data-md-level="3" aria-labelledby="__nav_3_2_2_label" aria-expanded="false"> <label class="md-nav__title" for="__nav_3_2_2"> For groups </label> <ul class="md-nav__list" data-md-scrollfix> <li class="md-nav__item"> <a href="../../b2drop/groups/" class="md-nav__link"> Overview </a> </li> </ul> </nav> </li> </ul> </nav> </li> <li class="md-nav__item md-nav__item--nested"> <input class="md-nav__toggle md-toggle " type="checkbox" id="__nav_3_3" > <label class="md-nav__link" for="__nav_3_3" id="__nav_3_3_label" tabindex="0"> For Administrators </label> <nav class="md-nav" data-md-level="2" aria-labelledby="__nav_3_3_label" aria-expanded="false"> <label class="md-nav__title" for="__nav_3_3"> For Administrators </label> <ul class="md-nav__list" data-md-scrollfix> <li class="md-nav__item"> <a href="../../b2drop/admin/" class="md-nav__link"> Overview </a> </li> <li class="md-nav__item"> <a href="../../b2drop/b2sharebridge/" class="md-nav__link"> Enabling the B2SHAREbridge </a> </li> <li class="md-nav__item"> <a href="../../b2drop/setup/" class="md-nav__link"> Install B2DROP </a> </li> <li class="md-nav__item"> <a href="../../b2drop/integration/" class="md-nav__link"> Integrate with B2ACCESS </a> </li> </ul> </nav> </li> <li class="md-nav__item"> <a href="../../b2drop/about/" class="md-nav__link"> About </a> </li> </ul> </nav> </li> <li class="md-nav__item md-nav__item--nested"> <input class="md-nav__toggle md-toggle " type="checkbox" id="__nav_4" > <label class="md-nav__link" for="__nav_4" id="__nav_4_label" tabindex="0"> B2FIND </label> <nav class="md-nav" data-md-level="1" aria-labelledby="__nav_4_label" aria-expanded="false"> <label class="md-nav__title" for="__nav_4"> B2FIND </label> <ul class="md-nav__list" data-md-scrollfix> <li class="md-nav__item"> <a href="../../b2find/" class="md-nav__link"> Overview </a> </li> <li class="md-nav__item"> <a href="../../b2find/forusers/" class="md-nav__link"> For Users </a> </li> <li class="md-nav__item"> <a href="../../b2find/forproviders/" class="md-nav__link"> For Providers </a> </li> <li class="md-nav__item"> <a href="../../b2find/about/" class="md-nav__link"> About </a> </li> </ul> </nav> </li> <li class="md-nav__item md-nav__item--nested"> <input class="md-nav__toggle md-toggle " type="checkbox" id="__nav_5" > <label class="md-nav__link" for="__nav_5" id="__nav_5_label" tabindex="0"> B2HANDLE </label> <nav class="md-nav" data-md-level="1" aria-labelledby="__nav_5_label" aria-expanded="false"> <label class="md-nav__title" for="__nav_5"> B2HANDLE </label> <ul class="md-nav__list" data-md-scrollfix> <li class="md-nav__item"> <a href="../../b2handle/" class="md-nav__link"> Overview </a> </li> <li class="md-nav__item"> <a href="../../b2handle/foradministrators/" class="md-nav__link"> For Administrators </a> </li> <li class="md-nav__item md-nav__item--nested"> <input class="md-nav__toggle md-toggle " type="checkbox" id="__nav_5_3" > <label class="md-nav__link" for="__nav_5_3" id="__nav_5_3_label" tabindex="0"> For Developers </label> <nav class="md-nav" data-md-level="2" aria-labelledby="__nav_5_3_label" aria-expanded="false"> <label class="md-nav__title" for="__nav_5_3"> For Developers </label> <ul class="md-nav__list" data-md-scrollfix> <li class="md-nav__item"> <a href="../../b2handle/fordevelopers/" class="md-nav__link"> Overview </a> </li> <li class="md-nav__item"> <a href="../../b2handle/fordevelopers_pyhandle/" class="md-nav__link"> PyHandle for Developers </a> </li> <li class="md-nav__item"> <a href="../../b2handle/fordevelopers_b2handle/" class="md-nav__link"> B2Handle for Developers </a> </li> <li class="md-nav__item"> <a href="../../b2handle/fordevelopers_api/" class="md-nav__link"> API for Developers </a> </li> </ul> </nav> </li> <li class="md-nav__item md-nav__item--nested"> <input class="md-nav__toggle md-toggle " type="checkbox" id="__nav_5_4" > <label class="md-nav__link" for="__nav_5_4" id="__nav_5_4_label" tabindex="0"> Information </label> <nav class="md-nav" data-md-level="2" aria-labelledby="__nav_5_4_label" aria-expanded="false"> <label class="md-nav__title" for="__nav_5_4"> Information </label> <ul class="md-nav__list" data-md-scrollfix> <li class="md-nav__item"> <a href="../../b2handle/ownership/" class="md-nav__link"> Ownership </a> </li> <li class="md-nav__item"> <a href="../../b2handle/security/" class="md-nav__link"> Security </a> </li> </ul> </nav> </li> <li class="md-nav__item"> <a href="../../b2handle/more/" class="md-nav__link"> More Info </a> </li> <li class="md-nav__item"> <a href="../../b2handle/about/" class="md-nav__link"> About </a> </li> </ul> </nav> </li> <li class="md-nav__item md-nav__item--nested"> <input class="md-nav__toggle md-toggle " type="checkbox" id="__nav_6" > <label class="md-nav__link" for="__nav_6" id="__nav_6_label" tabindex="0"> B2INST </label> <nav class="md-nav" data-md-level="1" aria-labelledby="__nav_6_label" aria-expanded="false"> <label class="md-nav__title" for="__nav_6"> B2INST </label> <ul class="md-nav__list" data-md-scrollfix> <li class="md-nav__item"> <a href="../../b2inst/" class="md-nav__link"> Overview </a> </li> <li class="md-nav__item md-nav__item--nested"> <input class="md-nav__toggle md-toggle " type="checkbox" id="__nav_6_2" > <label class="md-nav__link" for="__nav_6_2" id="__nav_6_2_label" tabindex="0"> For Users </label> <nav class="md-nav" data-md-level="2" aria-labelledby="__nav_6_2_label" aria-expanded="false"> <label class="md-nav__title" for="__nav_6_2"> For Users </label> <ul class="md-nav__list" data-md-scrollfix> <li class="md-nav__item"> <a href="../../b2inst/forusers/" class="md-nav__link"> Overview </a> </li> <li class="md-nav__item"> <a href="../../b2inst/advancedsearch/" class="md-nav__link"> Advanced Search </a> </li> <li class="md-nav__item"> <a href="../../b2inst/httpapi/" class="md-nav__link"> HTTP REST API </a> </li> </ul> </nav> </li> <li class="md-nav__item"> <a href="../../b2inst/foradministrators/" class="md-nav__link"> For Administrators </a> </li> <li class="md-nav__item"> <a href="../../b2inst/fordevelopers/" class="md-nav__link"> For Developers </a> </li> <li class="md-nav__item"> <a href="../../b2inst/about/" class="md-nav__link"> About </a> </li> </ul> </nav> </li> <li class="md-nav__item md-nav__item--nested"> <input class="md-nav__toggle md-toggle " type="checkbox" id="__nav_7" > <label class="md-nav__link" for="__nav_7" id="__nav_7_label" tabindex="0"> B2SAFE </label> <nav class="md-nav" data-md-level="1" aria-labelledby="__nav_7_label" aria-expanded="false"> <label class="md-nav__title" for="__nav_7"> B2SAFE </label> <ul class="md-nav__list" data-md-scrollfix> <li class="md-nav__item"> <a href="../../b2safe/" class="md-nav__link"> Overview </a> </li> <li class="md-nav__item"> <a href="../../b2safe/forusers/" class="md-nav__link"> For Users </a> </li> <li class="md-nav__item"> <a href="../../b2safe/foradministrators/" class="md-nav__link"> For Administrators </a> </li> <li class="md-nav__item"> <a href="../../b2safe/fordevelopers/" class="md-nav__link"> For Developers </a> </li> <li class="md-nav__item"> <a href="../../b2safe/about/" class="md-nav__link"> About </a> </li> </ul> </nav> </li> <li class="md-nav__item md-nav__item--active md-nav__item--section md-nav__item--nested"> <input class="md-nav__toggle md-toggle " type="checkbox" id="__nav_8" checked> <label class="md-nav__link" for="__nav_8" id="__nav_8_label" tabindex=""> B2SHARE </label> <nav class="md-nav" data-md-level="1" aria-labelledby="__nav_8_label" aria-expanded="true"> <label class="md-nav__title" for="__nav_8"> B2SHARE </label> <ul class="md-nav__list" data-md-scrollfix> <li class="md-nav__item"> <a href="../overview/" class="md-nav__link"> Overview </a> </li> <li class="md-nav__item md-nav__item--section md-nav__item--nested"> <input class="md-nav__toggle md-toggle " type="checkbox" id="__nav_8_2" > <label class="md-nav__link" for="__nav_8_2" id="__nav_8_2_label" tabindex=""> For Users </label> <nav class="md-nav" data-md-level="2" aria-labelledby="__nav_8_2_label" aria-expanded="false"> <label class="md-nav__title" for="__nav_8_2"> For Users </label> <ul class="md-nav__list" data-md-scrollfix> <li class="md-nav__item"> <a href="../forusers/" class="md-nav__link"> Overview </a> </li> <li class="md-nav__item"> <a href="../advancedsearch/" class="md-nav__link"> Advance Search </a> </li> <li class="md-nav__item md-nav__item--active"> <input class="md-nav__toggle md-toggle" type="checkbox" id="__toc"> <label class="md-nav__link md-nav__link--active" for="__toc"> HTTP REST API </label> <a href="./" class="md-nav__link md-nav__link--active"> HTTP REST API </a> <nav class="md-nav md-nav--secondary" aria-label="Table of contents"> <label class="md-nav__title" for="__toc"> Table of contents </label> <ul class="md-nav__list" data-md-component="toc" data-md-scrollfix> <li class="md-nav__item"> <a href="#eudat-b2share-http-rest-api" class="md-nav__link"> EUDAT B2SHARE HTTP REST API. </a> <nav class="md-nav" aria-label="EUDAT B2SHARE HTTP REST API."> <ul class="md-nav__list"> <li class="md-nav__item"> <a href="#guidelines" class="md-nav__link"> Guidelines </a> </li> <li class="md-nav__item"> <a href="#the-rest-api" class="md-nav__link"> The REST API </a> </li> <li class="md-nav__item"> <a href="#basic-concepts" class="md-nav__link"> Basic concepts </a> </li> <li class="md-nav__item"> <a href="#editing-and-versioning-records" class="md-nav__link"> Editing and versioning records </a> </li> <li class="md-nav__item"> <a href="#using-the-api" class="md-nav__link"> Using the API </a> </li> <li class="md-nav__item"> <a href="#authentication" class="md-nav__link"> Authentication </a> </li> <li class="md-nav__item"> <a href="#requests" class="md-nav__link"> Requests </a> </li> <li class="md-nav__item"> <a href="#responses" class="md-nav__link"> Responses </a> </li> <li class="md-nav__item"> <a href="#a-publication-workflow" class="md-nav__link"> A publication workflow </a> </li> <li class="md-nav__item"> <a href="#migrating-to-the-b2share-v2-http-rest-api" class="md-nav__link"> Migrating to the B2SHARE v2 HTTP REST API </a> </li> <li class="md-nav__item"> <a href="#available-http-rest-api-requests" class="md-nav__link"> Available HTTP REST API requests </a> </li> <li class="md-nav__item"> <a href="#object-retrieval" class="md-nav__link"> Object retrieval </a> </li> <li class="md-nav__item"> <a href="#record-administration" class="md-nav__link"> Record administration </a> </li> <li class="md-nav__item"> <a href="#record-versioning" class="md-nav__link"> Record versioning </a> </li> <li class="md-nav__item"> <a href="#other-requests" class="md-nav__link"> Other requests </a> </li> <li class="md-nav__item"> <a href="#support" class="md-nav__link"> Support </a> </li> </ul> </nav> </li> </ul> </nav> </li> </ul> </nav> </li> <li class="md-nav__item md-nav__item--section md-nav__item--nested"> <input class="md-nav__toggle md-toggle " type="checkbox" id="__nav_8_3" > <label class="md-nav__link" for="__nav_8_3" id="__nav_8_3_label" tabindex=""> For Developers </label> <nav class="md-nav" data-md-level="2" aria-labelledby="__nav_8_3_label" aria-expanded="false"> <label class="md-nav__title" for="__nav_8_3"> For Developers </label> <ul class="md-nav__list" data-md-scrollfix> <li class="md-nav__item"> <a href="../fordevelopers/" class="md-nav__link"> Overview </a> </li> </ul> </nav> </li> <li class="md-nav__item md-nav__item--active md-nav__item--section md-nav__item--nested"> <input class="md-nav__toggle md-toggle " type="checkbox" id="__nav_8_4" checked> <label class="md-nav__link" for="__nav_8_4" id="__nav_8_4_label" tabindex=""> For Administrators </label> <nav class="md-nav" data-md-level="2" aria-labelledby="__nav_8_4_label" aria-expanded="true"> <label class="md-nav__title" for="__nav_8_4"> For Administrators </label> <ul class="md-nav__list" data-md-scrollfix> <li class="md-nav__item"> <a href="../foradministrators/" class="md-nav__link"> Overview </a> </li> <li class="md-nav__item"> <a href="../cli/" class="md-nav__link"> Command Line Interface (CLI) </a> </li> <li class="md-nav__item md-nav__item--active"> <input class="md-nav__toggle md-toggle" type="checkbox" id="__toc"> <label class="md-nav__link md-nav__link--active" for="__toc"> HTTP REST API </label> <a href="./" class="md-nav__link md-nav__link--active"> HTTP REST API </a> <nav class="md-nav md-nav--secondary" aria-label="Table of contents"> <label class="md-nav__title" for="__toc"> Table of contents </label> <ul class="md-nav__list" data-md-component="toc" data-md-scrollfix> <li class="md-nav__item"> <a href="#eudat-b2share-http-rest-api" class="md-nav__link"> EUDAT B2SHARE HTTP REST API. </a> <nav class="md-nav" aria-label="EUDAT B2SHARE HTTP REST API."> <ul class="md-nav__list"> <li class="md-nav__item"> <a href="#guidelines" class="md-nav__link"> Guidelines </a> </li> <li class="md-nav__item"> <a href="#the-rest-api" class="md-nav__link"> The REST API </a> </li> <li class="md-nav__item"> <a href="#basic-concepts" class="md-nav__link"> Basic concepts </a> </li> <li class="md-nav__item"> <a href="#editing-and-versioning-records" class="md-nav__link"> Editing and versioning records </a> </li> <li class="md-nav__item"> <a href="#using-the-api" class="md-nav__link"> Using the API </a> </li> <li class="md-nav__item"> <a href="#authentication" class="md-nav__link"> Authentication </a> </li> <li class="md-nav__item"> <a href="#requests" class="md-nav__link"> Requests </a> </li> <li class="md-nav__item"> <a href="#responses" class="md-nav__link"> Responses </a> </li> <li class="md-nav__item"> <a href="#a-publication-workflow" class="md-nav__link"> A publication workflow </a> </li> <li class="md-nav__item"> <a href="#migrating-to-the-b2share-v2-http-rest-api" class="md-nav__link"> Migrating to the B2SHARE v2 HTTP REST API </a> </li> <li class="md-nav__item"> <a href="#available-http-rest-api-requests" class="md-nav__link"> Available HTTP REST API requests </a> </li> <li class="md-nav__item"> <a href="#object-retrieval" class="md-nav__link"> Object retrieval </a> </li> <li class="md-nav__item"> <a href="#record-administration" class="md-nav__link"> Record administration </a> </li> <li class="md-nav__item"> <a href="#record-versioning" class="md-nav__link"> Record versioning </a> </li> <li class="md-nav__item"> <a href="#other-requests" class="md-nav__link"> Other requests </a> </li> <li class="md-nav__item"> <a href="#support" class="md-nav__link"> Support </a> </li> </ul> </nav> </li> </ul> </nav> </li> </ul> </nav> </li> <li class="md-nav__item"> <a href="../faq/" class="md-nav__link"> F.A.Q.s </a> </li> <li class="md-nav__item"> <a href="../about/" class="md-nav__link"> About </a> </li> </ul> </nav> </li> <li class="md-nav__item md-nav__item--nested"> <input class="md-nav__toggle md-toggle " type="checkbox" id="__nav_9" > <label class="md-nav__link" for="__nav_9" id="__nav_9_label" tabindex="0"> DataCite </label> <nav class="md-nav" data-md-level="1" aria-labelledby="__nav_9_label" aria-expanded="false"> <label class="md-nav__title" for="__nav_9"> DataCite </label> <ul class="md-nav__list" data-md-scrollfix> <li class="md-nav__item"> <a href="../../datacite/" class="md-nav__link"> Overview </a> </li> <li class="md-nav__item"> <a href="../../datacite/forusers/" class="md-nav__link"> For Users </a> </li> <li class="md-nav__item"> <a href="../../datacite/about/" class="md-nav__link"> About </a> </li> </ul> </nav> </li> <li class="md-nav__item"> <a href="https://eudat.eu" class="md-nav__link"> EUDAT website </a> </li> <li class="md-nav__item"> <a href="https://eudat.eu/contact-support-request" class="md-nav__link"> Feedback + Support </a> </li> </ul> </nav> </div> </div> </div> <div class="md-content" data-md-component="content"> <article class="md-content__inner md-typeset"> <h1>HTTP REST API</h1> <h2 id="eudat-b2share-http-rest-api">EUDAT B2SHARE HTTP REST API.<a class="headerlink" href="#eudat-b2share-http-rest-api" title="Permanent link">#</a></h2> <h3 id="guidelines">Guidelines<a class="headerlink" href="#guidelines" title="Permanent link">#</a></h3> B2SHARE is the EUDAT service for storing and publishing data sets. In addition to its web-based GUI, B2SHARE offers an HTTP REST API. External applications or workflows can use this API, for example, to integrate B2SHARE with other websites like research community portals, or to allow uploads and downloads of large data sets that are not easily handled via a web browser. The API functionality is also used for metadata harvesting by external metadata catalogue services, including B2FIND. <h3 id="the-rest-api">The REST API<a class="headerlink" href="#the-rest-api" title="Permanent link">#</a></h3> B2SHARE provides a graphical, web-based interface, whose functionality is discussed in the corresponding <a href="../overview/">user documentation page</a>. The B2HARE HTTP REST API can be used for interaction with B2SHARE via external services or applications, for example for integration with other web-sites (research community portals) or for uploading or downloading large data sets that are not easily handled via a web browser. The API can also be used for metadata harvesting, although an OAI-PMH API endpoint is also provided for this purpose. This latter API will not be discussed here. This page will explain the basic concepts, authentication and all existing HTTP requests that can currently be used. The given examples are explained using curl commands. For usage of the API with Python, please follow the <a href="https://github.com/EUDAT-Training/B2SHARE-Training">training material</a> provided by EUDAT. <blockquote> Note : before B2SHARE-v.2.3.0 REST API was referred to as HTTP API </blockquote> <h3 id="basic-concepts">Basic concepts<a class="headerlink" href="#basic-concepts" title="Permanent link">#</a></h3> The B2SHARE service uses several concepts which are briefly explained below. A scientific community has the roles of creating and maintaining metadata schemas and curating the datasets which are part of a scientific domain or research project. B2SHARE users can be part of one or more communities. Some selected members of a community are also given the role of community administrators, which grants them the special rights needed for the schema definitions and record curation tasks. Any user can upload scientific datasets into B2SHARE and thus create data records. A record is comprised of data files and associated metadata. The record’s metadata consists of a set of common fixed metadata field and a set of custom metadata blocks, each block containing related metadata fields. A record is always connected to one scientific community which has the role of curating and maintaining it. A record contains a set of common metadata fields and a set of custom metadata blocks. This metadata is not free form, however, but is governed by static schemas; the common metadata schema is set by B2SHARE and defines a superset of Dublin Core elements, while the schema for the custom metadata block is specific to each community and can be customized by the community administrators. The schemas are formally defined in the JSON Schema format. A special HTTP REST API call is available for retrieving the JSON Schema of a record in a specific community. In order to be accepted, the records submitted to a community must conform to the schema required by the community. <h3 id="editing-and-versioning-records">Editing and versioning records<a class="headerlink" href="#editing-and-versioning-records" title="Permanent link">#</a></h3> A data record can exist in several states. Immediately after creation a record enters the ‘draft’ state. In this state the record is only accessible by its owner and can be freely modified: its metadata can be changed and files can be uploaded into or removed from it. A draft can be published at any time, and through this action it changes its state from ‘draft’ to ‘published’, is assigned Persistent Identifiers, and becomes publicly accessible. Please note that the list of files in a published record cannot be changed without versioning the record. To update the metadata of a record through the API, a <a href="https://jsonpatch.com/">JSON Patch</a> must be supplied with the request. Please read the documentation on this website carefully to fully understand how these patches work. In the request below, the term ‘JSONPath’ is used which indicates a path in the metadata relative to the root of the structure. Existing published records can be versioned by creating a derivative draft that initially is a clone of the original record. This draft record can be changed in metadata but also files. A link will be established to the original record so that anyone can find and compare the contents of the versioned and original record. There is no limit to the number of versions created per record. A new versioned record needs to be published before it becomes available to other users. <h3 id="using-the-api">Using the API<a class="headerlink" href="#using-the-api" title="Permanent link">#</a></h3> The REST API is used by making API requests using the GET or POST methods of the standard HTTP protocol. Typically an application like curl is used to make requests, but it is also possible to do this from within your custom-built applications. To intergrate the API in your application using Python, please refer to the <a href="https://github.com/EUDAT-Training/B2SHARE-Training/tree/master/api">B2SHARE API training module</a> to learn how to use the API. <h3 id="authentication">Authentication<a class="headerlink" href="#authentication" title="Permanent link">#</a></h3> Although listing and accessing public data is not access-controlled, only authenticated users can use the API to its full extent. Authentication during requests is done by passing an access token along with the request. The access token is an encrypted string which can be created in the B2SHARE user profile when logged in to the web user interface. B2SHARE’s access tokens follow the OAuth 2.0 standard. <h4 id="creating-an-access-token">Creating an access token<a class="headerlink" href="#creating-an-access-token" title="Permanent link">#</a></h4> After logging in to the B2SHARE service click your user name and select ‘Profile’. Under ‘API tokens’, enter a token name (Figure 1). <h5 id="step-1-applications">Step 1: Applications.<a class="headerlink" href="#step-1-applications" title="Permanent link">#</a></h5> <img alt="B2SHAREcreate API token" src="../images/httpapi/B2SHARE-API-create-api-token-1000.png" /> Figure 1. B2SHARE Access Token. (Step 1: Applications) Click “New token” on the right of the text box. Your token is now created and immediately displayed (Figure 2). Please note that this is the only time the access token is visible, so copy it to a safe place. <h5 id="step-2-create-new-token">Step 2: Create new token<a class="headerlink" href="#step-2-create-new-token" title="Permanent link">#</a></h5> <img alt="B2SHARE API tokens" src="../images/httpapi/B2SHARE-API-api-tokens-1000-3.png" /> Figure 2. B2SHARE Access Token. (Step 2: Create new token) The access token is now ready for use. Access tokens can be removed by clicking on the remove button next to each access token name. The following shell commands will expect that the <code>ACCESS_TOKEN</code> environment variable is defined and contains the actual access token. The command to define this variable looks like this: Command: <div class="highlight"><pre><code>export ACCESS_TOKEN='<personal_access_token>' </code></pre></div> example: <div class="highlight"><pre><code>export ACCESS_TOKEN='LMlLGmlzwo3NtDNAqIUxbb5fxq0Mr8xmS7r8gEACogHTYRpP3EIevbbSoyba' </code></pre></div> <blockquote> Notes: </blockquote> <ul> <li>Please remember to use your actual token instead of the one given as an example above.</li> <li>Your token can only be used for the instance you created the token in. That means that a token for the training instance of B2SHARE will not work with the production instance of B2SHARE and vice-versa!</li> </ul> <h3 id="requests">Requests<a class="headerlink" href="#requests" title="Permanent link">#</a></h3> The API requests are made to a URL with parameters as described below. Each URL consists of a protocol part (always ‘https://’), a hostname and a path. One of the following hostnames can be used to identify the B2SHARE instance: <ul> <li>https://b2share.eudat.eu - the hostname for the production site.</li> <li>https://trng-b2share.eudat.eu - the hostname for the training site. Use this base URL for testing.</li> </ul> <blockquote> Notes: - Please make sure that you are not using production instances for creating test records or testing the API in general. - Make sure to add a forward-slash (‘/’) to the URL if that is required. If you forget the slash then the request is interpreted differently and you might get other results than expected. In many cases, a redirect (status code 302) will be returned, a result that in the browser will be handled automatically, but not in a typical API request. </blockquote> The curl commands in the examples of each request will expect that the HOST environment variable is defined and contains the host part of the targeted B2SHARE site, e.g.: Command: <div class="highlight"><pre><code>export B2SHARE_HOST='trng-b2share.eudat.eu' </code></pre></div> <h3 id="responses">Responses<a class="headerlink" href="#responses" title="Permanent link">#</a></h3> All request response bodies are JSON encoded (UTF-8 encoded). A record is represented as a JSON object: <div class="highlight"><pre><code>{ "field1": "value" } </code></pre></div> A collection of records is represented as a JSON array of objects: <div class="highlight"><pre><code>{ "collection": [ { "field1": "value", "field2": "value" }, { "field1": "value", "field2": "value" } ] } </code></pre></div> Timestamps are in UTC and formatted according to ISO 8601: <div class="highlight"><pre><code>{ "updated": "YYYY-MM-DDTHH:MM:SS.ssssss+00:00" } </code></pre></div> In case a request fails, the body of the response body contains details about the error, for Command: <div class="highlight"><pre><code>{ "message": "The requested URL was not found on the server. If you entered the URL manually please check your spelling and try again.", "status": 404 } </code></pre></div> Here in the message field provides a detailed description of what went wrong, while the code indicates the HTTP status code (equivalent to the request response status code). <h4 id="status-codes">Status codes<a class="headerlink" href="#status-codes" title="Permanent link">#</a></h4> The request status codes indicate whether the request was successfully received, processed and/or executed. B2SHARE follows the HTTP status codes where possible, a complete list can be found here. One of the following status codes is returned in case the request was successful: <div class="highlight"><pre><code>200 : Request was successfully received and executed, see body for results 201 : Object created, see body for results 204 : No contents, this occurs when for example an object is successfully deleted </code></pre></div> In case the request failed, the body of the response usually contains details, and one of the following status codes is returned: <div class="highlight"><pre><code>400 : Request was not understood 401 : User must authenticate first, usually because no access token was provided with the request 403 : User is not authorized to perform request, missing permission to do so 404 : Requested object not found or API endpoint does not exist </code></pre></div> Any status code greater then or equal to 500 indicates that internally something went wrong in the server. If in this case the problem persists, kindly report this to EUDAT. <h3 id="a-publication-workflow">A publication workflow<a class="headerlink" href="#a-publication-workflow" title="Permanent link">#</a></h3> The HTTP REST API does not impose a specific workflow for creating a record. The following example workflow only defines the most basic steps: <ol> <li>Identify a target community for your data by using the HTTP REST API <a href="#list-all-communities">List all communities</a> function</li> <li>Using the community’s identifier, retrieve the JSON Schema of the record’s metadata. The submitted metadata will have to conform to this schema. Use the <a href="#get-community-schema">Get community schema</a> function</li> <li>Create a draft record: use the <a href="#create-draft-record">Create draft record</a> function</li> <li>Upload the files into the draft record. You will have to use one HTTP request per file. Use the <a href="#upload-file-into-draft-record">Upload file</a> function</li> <li>Set the complete metadata and publish the record. Use the <a href="#submit-draft-record-for-publication">Submit draft for publication</a> function</li> </ol> <h3 id="migrating-to-the-b2share-v2-http-rest-api">Migrating to the B2SHARE v2 HTTP REST API<a class="headerlink" href="#migrating-to-the-b2share-v2-http-rest-api" title="Permanent link">#</a></h3> The following changes are needed for a B2SHARE version 1 client using the old HTTP REST API in order to make it work with B2SHARE version 2 for creating and publishing a record: <ul> <li>Identify the unique ID of your target community or communities: see <a href="#list-all-communities">List all communities</a> function</li> <li>Update the URL for creating a new record, from <code>/api/deposition/</code> to <code>/api/records/</code>; see <a href="#create-draft-record">Create draft record</a> function</li> <li>Update the JSON structure of the newly created records to match the required JSON schema structure, see the <a href="#get-community-schema">Get community schema</a> function</li> <li>Update the file upload calls, making sure that the file bucket url is used instead of the old record URL, see the <a href="#upload-file-into-draft-record">Upload file</a> function</li> <li>Update the old ‘commit’ action as described in the <a href="#submit-draft-record-for-publication">Submit draft for publication</a> function</li> </ul> <h3 id="available-http-rest-api-requests">Available HTTP REST API requests<a class="headerlink" href="#available-http-rest-api-requests" title="Permanent link">#</a></h3> Each allowed request is described as follows: <div class="highlight"><pre><code> Description : A description of the function of the request. HTTP method : which HTTP protocol such as GET or POST method is used. URL path : grammar for the allowed paths used together with one of the base URLs above. Status code : the returned status code upon a successful request. Returns : the returned data in the body of the response upon a successful request. Example : an example of usage using the program curl from the command line. </code></pre></div> Some of the requests additionally might have the following information: <div class="highlight"><pre><code> Required parameters : the parameters that need to be added to the URL. Required data : the data that needs to be sent with the request, the expected structure is shown in the example. </code></pre></div> Variables in the descriptions: <ul> <li> <code>RECORD_ID</code> - identifier for a specific record, which can be in draft or published state </li> <li> <code>RECORD_HEAD_ID</code> - head identifier for a group of record that are versions of each other </li> <li> <code>FILE_BUCKET_ID</code> - identifier for a set of files. Each record has its own file set, usually found in the links -> files section </li> <li> <code>COMMUNITY_ID</code> - identifier of a user community in B2SHARE </li> <li> <code>SCHEMA_ID</code> - identifier of a metadata schema in B2SHARE </li> <li> <code>FILE_NAME</code> - name of a file in a specific file bucket </li> <li> <code>FIELD_NAME</code> - name of a metadata field </li> </ul> For most requests, an example is shown using a curl command. If a payload is sent with the request, this is shown in a structured way below the example. The returned response body and request-specific errors are shown if applicable. <h3 id="object-retrieval">Object retrieval<a class="headerlink" href="#object-retrieval" title="Permanent link">#</a></h3> The following requests concern the retrieval of information about records and communities. <h4 id="list-all-communities">List all communities<a class="headerlink" href="#list-all-communities" title="Permanent link">#</a></h4> List all the communities, without any filtering. <ul> <li> HTTP method: <code>GET</code> </li> <li> URL path: <code>/api/communities/</code> </li> <li> Required parameters: <code>None</code> </li> <li> Status code on success: <code>200</code> </li> <li> Returns: the list of communities (in JSON format) or an error message. </li> </ul> Command: <div class="highlight"><pre><code>curl "https://$B2SHARE_HOST/api/communities/" </code></pre></div> Returns: <div class="highlight"><pre><code>{ "hits": { "hits": [ { "created": "Tue, 18 Oct 2016 08:30:47 GMT", "description": "The big Eudat community. Use this community if no other is suited for you", "id": "e9b9792e-79fb-4b07-b6b4-b9c2bd06d095", "links": { "self": "https://trng-b2share.eudat.eu/api/communities/e9b9792e-79fb-4b07-b6b4-b9c2bd06d095" }, "logo": "/img/communities/eudat.png", "name": "EUDAT", "updated": "Tue, 18 Oct 2016 08:30:47 GMT" }, ... ], "total": 11 }, "links": { "self": "https://trng-b2share.eudat.eu/api/communities/" } } </code></pre></div> <h4 id="get-community-schema">Get community schema<a class="headerlink" href="#get-community-schema" title="Permanent link">#</a></h4> Retrieves the JSON schema of records approved by a specific community. <div class="highlight"><pre><code> HTTP method: GET URL path: /api/communities/$COMMUNITY_ID/schemas/last Required parameters: None Status code on success: 200 Returns: the community metadata schema, embedded in a JSON object, or an error message. </code></pre></div> Command: <div class="highlight"><pre><code>curl "https://$B2SHARE_HOST/api/communities/$COMMUNITY_ID/schemas/last" </code></pre></div> Returns: <div class="highlight"><pre><code>{ "community": "e9b9792e-79fb-4b07-b6b4-b9c2bd06d095", "draft_json_schema": { "$ref": "https://trng-b2share.eudat.eu/api/communities/e9b9792e-79fb-4b07-b6b4-b9c2bd06d095/schemas/0#/json_schema", "$schema": "http://json-schema.org/draft-04/schema#" }, "json_schema": { "allOf": [ ... ] }, "links": { "self": "https://trng-b2share.eudat.eu/api/communities/e9b9792e-79fb-4b07-b6b4-b9c2bd06d095/schemas/0" }, "version": 0 } </code></pre></div> <h4 id="list-all-records">List all records<a class="headerlink" href="#list-all-records" title="Permanent link">#</a></h4> List all the records, without any filtering. <div class="highlight"><pre><code> HTTP method: GET URL path: /api/records/ Required parameters: None Optional parameters: page, size, mostrecent Status code on success: 200 Returns: the list of records (in JSON format) or an error message. </code></pre></div> Command: <div class="highlight"><pre><code>curl "https://$B2SHARE_HOST/api/records/" </code></pre></div> Returns: <div class="highlight"><pre><code>{ "aggregations": { "type": { "buckets": [], "doc_count_error_upper_bound": 0, "sum_other_doc_count": 0 } }, "hits": { "hits": [ { "created": "2016-10-19T11:32:46.095143+00:00", "files": [ { "bucket": "473086fc-e125-4389-8483-b8a4f130e181", "checksum": "md5:c8afdb36c52cf4727836669019e69222", "key": "myfile", "size": 9, "version_id": "324fdf1d-0005-41b1-a9c5-26a8eabd05a2" } ], "id": "a1c2ef96a1e446fa9bd7a2a46d2242d4", "links": { "files": "https://trng-b2share.eudat.eu/api/files/473086fc-e125-4389-8483-b8a4f130e181", "self": "https://trng-b2share.eudat.eu/api/records/a1c2ef96a1e446fa9bd7a2a46d2242d4" }, "metadata": { ...: ... }, "updated": "2016-10-19T11:32:46.095152+00:00" }, ... ], "total": 51 }, "links": { "next": "https://trng-b2share.eudat.eu/api/records/?sort=mostrecent&q=&page=2", "self": "https://trng-b2share.eudat.eu/api/records/?sort=mostrecent&q=&page=1" } } </code></pre></div> <h4 id="list-records-per-community">List records per community<a class="headerlink" href="#list-records-per-community" title="Permanent link">#</a></h4> List all records of a specific community. <div class="highlight"><pre><code> HTTP method: GET URL path: /api/records/ Required parameters: q with value community: COMMUNITY_ID Status code on success: 200 Returns: the list of records (in JSON format) or an error message </code></pre></div> <blockquote> Notes: - you can use search parameters to further narrow your search as described in the ‘Search records’ section. </blockquote> Command: <div class="highlight"><pre><code>curl "https://$B2SHARE_HOST/api/records/?q=community:$COMMUNITY_ID" </code></pre></div> Returns: <div class="highlight"><pre><code>{ "aggregations": { "type": { "buckets": [], "doc_count_error_upper_bound": 0, "sum_other_doc_count": 0 } }, "hits": { "hits": [ { "created": "2016-10-24T11:29:27.016892+00:00", "id": "f7fddf6f111f4362a9e4661294e2b59e", "links": { "files": "https://trng-b2share.eudat.eu/api/files/90ea3483-2792-4483-9392-7d624b610398", "self": "https://trng-b2share.eudat.eu/api/records/f7fddf6f111f4362a9e4661294e2b59e", "versions": "https://trng-b2share.eudat.eu/api/records/d855e187e3864ddcaa1b68625866dd78/versions" }, "updated": "2016-10-24T11:29:27.016900+00:00", ...: ... }, ... ], "total": 32 }, "links": { "next": "https://trng-b2share.eudat.eu/api/records/?sort=bestmatch&q=community%3Ae9b9792e-79fb-4b07-b6b4-b9c2bd06d095&size=10&page=2", "self": "https://trng-b2share.eudat.eu/api/records/?sort=bestmatch&q=community%3Ae9b9792e-79fb-4b07-b6b4-b9c2bd06d095&size=10&page=1" } } </code></pre></div> <h4 id="search-records">Search records<a class="headerlink" href="#search-records" title="Permanent link">#</a></h4> Search all the published records for a query string. <div class="highlight"><pre><code> HTTP method: GET URL path: /api/records/ Required parameters: none Optional parameters: q, page, size, sort Status code on success: 200 Returns: the list of matching records (in JSON format) or an error message </code></pre></div> <blockquote> Notes: - The parameter q determines the keywords to search for, separated by a space. - If a field name is prepended followed by a colon and the search value, the search is limited to that field, e.g. <code>'creators.creator:user'</code> searches for records with a ‘user’ in the creator metadata field. - If the parameter q is omitted, all records are returned (in paginated form). See also ‘List all records’. - For a better understanding of search queries, a listing of available search fields and advanced options like operators, please refer to the B2SHARE Advanced Search documentation on how to create them. - Using the page and size parameter, pagination can be established by providing integer values for these parameters. The page parameter is 1-based. - For example: using a value of 2 for page and 50 for size will return the records from number 51 to 100 (if there are at least 100 records available on the instance) - The sort parameter can be either <code>'mostrecent'</code> or <code>'bestmatch'</code>. </blockquote> Command: <div class="highlight"><pre><code>curl "https://$B2SHARE_HOST/api/records/?q=$QUERY_STRING&page=1&size=100&sort=mostrecent" </code></pre></div> <h4 id="search-drafts">Search drafts<a class="headerlink" href="#search-drafts" title="Permanent link">#</a></h4> List all your draft records <div class="highlight"><pre><code> HTTP method: GET URL path: /api/records/ Required parameters: access_token, drafts Optional parameters: q Status code on success: 200 Returns: the list of matching drafts (in JSON format) or an error message. </code></pre></div> <blockquote> Notes: - You can only list your own draft records. - You can add search parameters to narrow down your search, see ‘Search records’ </blockquote> Command: <div class="highlight"><pre><code>curl "https://$B2SHARE_HOST/api/records/?drafts&access_token=$ACCESS_TOKEN" </code></pre></div> <h4 id="get-specific-record">Get specific record<a class="headerlink" href="#get-specific-record" title="Permanent link">#</a></h4> List the metadata of the record specified by <code>RECORD_ID</code>. The metadata of all records are always public. <div class="highlight"><pre><code> HTTP method: GET URL path: /api/records/RECORD_ID Required parameters: access_token Status code on success: 200 </code></pre></div> <blockquote> Notes: - the access token is only required when a record is not publicly available. </blockquote> Command: <div class="highlight"><pre><code>curl "https://$B2SHARE_HOST/api/records/47077e3c4b9f4852a40709e338ad4620" </code></pre></div> <h3 id="record-administration">Record administration<a class="headerlink" href="#record-administration" title="Permanent link">#</a></h3> The following requests concern the creation, update and management of records. <h4 id="create-draft-record">Create draft record<a class="headerlink" href="#create-draft-record" title="Permanent link">#</a></h4> Create a new record, in the draft state. <div class="highlight"><pre><code> HTTP method: POST URL path: /api/records/ Required parameters: access_token Payload data: JSON object with basic metadata of the object, at least the required fields of the basic metadata schema of each new record: titles, community and open_access. Status code on success: 201 Returns: the new draft record metadata including new URL location. Please note that the returned JSON object contains also the URL of the file bucket used for the record. Also note that the URL of the draft record, needed for setting record metadata, will end in '/draft/' </code></pre></div> <blockquote> Notes: - you cannot change the community the record resides in after you have created the record. </blockquote> <h5 id="example-1">Example 1<a class="headerlink" href="#example-1" title="Permanent link">#</a></h5> The following example creates an open-access record for a community with identifier <code>e9b9792e-79fb-4b07-b6b4-b9c2bd06d095</code> with title <code>'My dataset record'</code>, creators <code>'John Smith' and 'Jane Smith'</code> and description of type abstract <code>'A simple description'</code>. Command: <div class="highlight"><pre><code>curl -X POST -H "Content-Type:application/json" -d '{"titles":[{"title":"My dataset record"}], "creators":[{"creator_name": "John Smith"}, {"creator_name": "Jane Smith"}], "descriptions":[{"description": "A simple description", "description_type": "Abstract"}], "community":"e9b9792e-79fb-4b07-b6b4-b9c2bd06d095", "open_access":true}' "https://$B2SHARE_HOST/api/records/?access_token=$ACCESS_TOKEN" </code></pre></div> Payload: <div class="highlight"><pre><code>{ "titles": [ { "title": "My dataset record" } ], "creators": [ { "creator_name": "John Smith" }, { "creator_name": "Jane Smith" } ], "descriptions": [ { "description": "A simple description", "description_type": "Abstract" } ], "community": "e9b9792e-79fb-4b07-b6b4-b9c2bd06d095", "open_access": true, } </code></pre></div> Returns: <div class="highlight"><pre><code>{ "created": "2016-10-24T12:21:21.697737+00:00", "id": "01826ff3e4974415afdb2574a7ea5a91", "links": { "files": "https://trng-b2share.eudat.eu/api/files/5594a1bf-1484-4a01-b7d3-f1eb3d2e1dc6", "publication": "https://trng-b2share.eudat.eu/api/records/01826ff3e4974415afdb2574a7ea5a91", "self": "https://trng-b2share.eudat.eu/api/records/01826ff3e4974415afdb2574a7ea5a91/draft", "versions": "https://trng-b2share.eudat.eu/api/records/d855e187e3864ddcaa1b68625866dd78/versions" }, "metadata": { "$schema": "https://trng-b2share.eudat.eu/api/communities/e9b9792e-79fb-4b07-b6b4-b9c2bd06d095/schemas/0#/draft_json_schema", "community": "e9b9792e-79fb-4b07-b6b4-b9c2bd06d095", "community_specific": { "field_1": "value_1", "field_2": "value_2" }, "open_access": true, "owners": [ 8 ], "publication_state": "draft", "titles": [ { "title": "My dataset record" } ], "creators": [ { "creator_name": "John Smith" }, { "creator_name": "Jane Smith" } ] }, "updated": "2016-10-24T12:21:21.697744+00:00" } </code></pre></div> <h5 id="example-2">Example 2<a class="headerlink" href="#example-2" title="Permanent link">#</a></h5> The next example creates an open-access record for a community with identifier <code>94a9567e-2fba-4677-8fde-a8b68bdb63e8</code> with title <code>'My community record'</code>, creator <code>'John Smith'</code>. The following community-specific fields are added: <code>'field_1'</code> and <code>'field_2'</code>. For this to work, the schema identifier of the community metadata schema is required. You can get this information from the community metadata using the <a href="#get-community-schema">Get community schema</a> request, although it is a bit hidden. The correct JSONPath for this metadata is <code>/json_schema/allOf/1/yml/community_specific/required</code>, in this example <code>5108aff5-be5b-4d92-968a-22930ee65e94</code>. `` Command: <div class="highlight"><pre><code>curl -X POST -H "Content-Type:application/json" -d '{"titles":[{"title":"My community record"}], "creators":[{"creator_name": "John Smith"}], "community":"94a9567e-2fba-4677-8fde-a8b68bdb63e8", "open_access":true, "community_specific": {"5108aff5-be5b-4d92-968a-22930ee65e94": {"field_1": "value", "field_2": "value"}}}' "https://$B2SHARE_HOST/api/records/?access_token=$ACCESS_TOKEN" </code></pre></div> Payload: <div class="highlight"><pre><code>{ "titles": [ { "title": "My community record" } ], "creators": [ { "creator_name": "John Smith" } ], "community": "94a9567e-2fba-4677-8fde-a8b68bdb63e8", "open_access": true, "community_specific": { "5108aff5-be5b-4d92-968a-22930ee65e94": { "field_1": "value", "field_2": "value" } } } </code></pre></div> Returns: <div class="highlight"><pre><code>{ "created": "2016-10-24T12:21:21.697737+00:00", "id": "01826ff3e4974415afdb2574a7ea5a91", "links": { "files": "https://trng-b2share.eudat.eu/api/files/5594a1bf-1484-4a01-b7d3-f1eb3d2e1dc6", "publication": "https://trng-b2share.eudat.eu/api/records/01826ff3e4974415afdb2574a7ea5a91", "self": "https://trng-b2share.eudat.eu/api/records/01826ff3e4974415afdb2574a7ea5a91/draft", "versions": "https://trng-b2share.eudat.eu/api/records/d855e187e3864ddcaa1b68625866dd78/versions" }, "metadata": { "$schema": "https://trng-b2share.eudat.eu/api/communities/94a9567e-2fba-4677-8fde-a8b68bdb63e8/schemas/0#/draft_json_schema", "community": "94a9567e-2fba-4677-8fde-a8b68bdb63e8", "community_specific": { "5108aff5-be5b-4d92-968a-22930ee65e94": { "field_1": "value_1", "field_2": "value_2" } }, "open_access": true, "owners": [ 8 ], "publication_state": "draft", "titles": [ { "title": "My community record" } ], "creators": [ { "creator_name": "John Smith" }, { "creator_name": "Jane Smith" } ] }, "updated": "2016-10-24T12:21:21.697744+00:00" } </code></pre></div> <h5 id="common-errors">Common errors<a class="headerlink" href="#common-errors" title="Permanent link">#</a></h5> On metadata validation error: <div class="highlight"><pre><code>{ "message": "Validation error.", "status": 400 } </code></pre></div> The supplied metadata is invalid or incorrectly structured. This means that either a specified field does not exist in the metadata schema, or that one of the values for a given field is invalid. <h4 id="upload-file-into-draft-record">Upload file into draft record<a class="headerlink" href="#upload-file-into-draft-record" title="Permanent link">#</a></h4> To upload a new file into a draft record object, first you need to identify the file bucket URL. This URL can be found in the information returned when querying a draft record, in the ‘links/files’ section of the returned data. <div class="highlight"><pre><code> HTTP method: PUT URL path: /api/files/FILE_BUCKET_ID/FILE_NAME Required parameters: access_token Payload data: the file, sent as direct stream, for curl use the --data-binary @FILE_NAME option for this. Status code on success: 200 Returns: informations about the newly uploaded file </code></pre></div> <blockquote> Notes: - Using the <code>--data-binary</code> option will load the entire file into memory before being sent to B2SHARE - For large files instead use the <code>-T</code> option followed by the file name (without a <code>@</code>sign) - Also, to avoid timeouts please use the <code>-H "Transfer-Encoding: chunked"</code> option to send a file in chunks instead of all at once. </blockquote> Command: <div class="highlight"><pre><code>curl -X PUT -H 'Accept:application/json' -H 'Content-Type:application/octet-stream' --data-binary @$FILE_NAME "https://$B2SHARE_HOST/api/files/$FILE_BUCKET_ID/$FILE_NAME?access_token=$ACCESS_TOKEN" </code></pre></div> Command: <div class="highlight"><pre><code>curl -X PUT -H 'Accept:application/json' -H 'Content-Type:application/octet-stream' -H 'Transfer-Encoding:chunked' -T $FILE_NAME "https://$B2SHARE_HOST/api/files/$FILE_BUCKET_ID/$FILE_NAME?access_token=$ACCESS_TOKEN" </code></pre></div> <h4 id="delete-file-from-draft-record">Delete file from draft record<a class="headerlink" href="#delete-file-from-draft-record" title="Permanent link">#</a></h4> Send a DELETE request to the file’s URL, which is the same URL used for uploading. <div class="highlight"><pre><code> HTTP method: DELETE URL path: /api/files/FILE_BUCKET_ID/FILE_NAME Required parameters: access_token Status code on success: 204 Returns: no content </code></pre></div> Command: <div class="highlight"><pre><code>curl -X DELETE -H 'Accept:application/json' "https://$B2SHARE_HOST/api/files/$FILE_BUCKET_ID/FileToBeRemoved.txt?access_token=$ACCESS_TOKEN" </code></pre></div> <h4 id="list-files-of-record">List files of record<a class="headerlink" href="#list-files-of-record" title="Permanent link">#</a></h4> List the files uploaded into a record object. For this request you need the FILE_BUCKET_ID which can be found in the metadata of the record. This does not include files that are referenced externally. <div class="highlight"><pre><code> HTTP method: GET URL path: /api/files/FILE_BUCKET_ID Required parameters: access_token Status code on success: 200 Returns: information about all the files in the record object </code></pre></div> <blockquote> Notes: - the access token is only required if the record is in draft state. </blockquote> Command: <div class="highlight"><pre><code>curl "https://$B2SHARE_HOST/api/files/$FILE_BUCKET_ID?access_token=$ACCESS_TOKEN" </code></pre></div> <h4 id="update-draft-record-metadata">Update draft record metadata<a class="headerlink" href="#update-draft-record-metadata" title="Permanent link">#</a></h4> This action updates the draft record with new information. <div class="highlight"><pre><code> HTTP method: PATCH URL path: /api/records/RECORD_ID/draft Required parameters: access_token Payload data: the metadata for the draft record to be updated, in the JSON Patch format (see http://jsonpatch.com/) Status code on success: 200 Returns: the updated metadata of the draft record. </code></pre></div> <blockquote> Notes: - The JSON Patch format contains one or more JSONPath strings. The root of these paths are the metadata object, as this is the only mutable object. For instance, to update the title field of the record, use this JSONPath: <code>/titles/title</code> </blockquote> <h5 id="example-1_1">Example 1<a class="headerlink" href="#example-1_1" title="Permanent link">#</a></h5> The following example adds two values to the metadata field <code>keywords</code> of an existing draft record. Command: <div class="highlight"><pre><code>curl -X PATCH -H 'Content-Type:application/json-patch+json' -d '[{"op": "add", "path":"/keywords", "value": ["keyword1", "keyword2"]}]' "https://$B2SHARE_HOST/api/records/$RECORD_ID/draft?access_token=$ACCESS_TOKEN" </code></pre></div> Returns: <div class="highlight"><pre><code>{ "created": "2016-10-24T12:21:21.697737+00:00", "id": "01826ff3e4974415afdb2574a7ea5a91", "links": { "files": "https://trng-b2share.eudat.eu/api/files/5594a1bf-1484-4a01-b7d3-f1eb3d2e1dc6", "publication": "https://trng-b2share.eudat.eu/api/records/01826ff3e4974415afdb2574a7ea5a91", "self": "https://trng-b2share.eudat.eu/api/records/01826ff3e4974415afdb2574a7ea5a91/draft", "versions": "https://trng-b2share.eudat.eu/api/records/d855e187e3864ddcaa1b68625866dd78/versions" }, "metadata": { "$schema": "https://trng-b2share.eudat.eu/api/communities/e9b9792e-79fb-4b07-b6b4-b9c2bd06d095/schemas/0#/draft_json_schema", "community": "e9b9792e-79fb-4b07-b6b4-b9c2bd06d095", "community_specific": {}, "keywords": [ "keyword1", "keyword2" ], "open_access": true, "owners": [ 8 ], "publication_state": "draft", "titles": [ { "title": "My community title" } ] }, "updated": "2016-10-24T12:23:59.454951+00:00" } </code></pre></div> <h5 id="example-2_1">Example 2<a class="headerlink" href="#example-2_1" title="Permanent link">#</a></h5> This example replaces the value of the title of a record. This requires a JSONPath <code>/titles/0/title</code> as we are updated an existing value of multivalued field. Command: <div class="highlight"><pre><code>curl -X PATCH -H 'Content-Type:application/json-patch+json' -d '[{"op": "replace", "path":"/titles/0/title", "value": ["The new title"]}]' "https://$B2SHARE_HOST/api/records/$RECORD_ID/draft?access_token=$ACCESS_TOKEN" </code></pre></div> Returns: <div class="highlight"><pre><code>{ "created": "2016-10-24T12:21:21.697737+00:00", "id": "01826ff3e4974415afdb2574a7ea5a91", "links": { "files": "https://trng-b2share.eudat.eu/api/files/5594a1bf-1484-4a01-b7d3-f1eb3d2e1dc6", "publication": "https://trng-b2share.eudat.eu/api/records/01826ff3e4974415afdb2574a7ea5a91", "self": "https://trng-b2share.eudat.eu/api/records/01826ff3e4974415afdb2574a7ea5a91/draft", "versions": "https://trng-b2share.eudat.eu/api/records/d855e187e3864ddcaa1b68625866dd78/versions" }, "metadata": { "$schema": "https://trng-b2share.eudat.eu/api/communities/e9b9792e-79fb-4b07-b6b4-b9c2bd06d095/schemas/0#/draft_json_schema", "community": "e9b9792e-79fb-4b07-b6b4-b9c2bd06d095", "community_specific": {}, "open_access": true, "owners": [ 8 ], "publication_state": "draft", "titles": [ { "title": "The new title" } ] }, "updated": "2016-10-24T12:23:59.454951+00:00" } </code></pre></div> <h5 id="example-3">Example 3<a class="headerlink" href="#example-3" title="Permanent link">#</a></h5> The next example updates the community-specific metadata fields <code>field_1</code> and <code>field_2</code> of an existing draft record of community with identifier <code>e9b9792e-79fb-4b07-b6b4-b9c2bd06d095</code>. Note that in order to update a community-specific field, the JSONPath <code>/community-specific/SCHEMA_ID/FIELD_NAME</code> is required which contains the schema identifier used by the community. For this to work, the block schema identifier of the community metadata schema is required. You can get this information from the community metadata using the <a href="#get-community-schema">Get community schema</a> request, although it is a bit hidden. The correct JSONPath for this metadata is <code>/json_schema/allOf/1/yml/community_specific/required</code>. Starting from B2SHARE version 2.1.4, you can get the block schema identifier on the corresponding <a href="https://b2share.eudat.eu/communities/CLARIN">community landing page</a> in the block schema at the bottom of the page. Command: <div class="highlight"><pre><code>curl -X POST -H "Content-Type:application/json-patch+json" -d '[{"op": "add", "path": "/community_specific/$SCHEMA_ID/field_1", "value": "value_1"}, {"op": "add", "path": "/community_specific/$SCHEMA_ID/field_2", "value": "value_2"}]' "https://$B2SHARE_HOST/api/records/$RECORD_ID/draft?access_token=$ACCESS_TOKEN" </code></pre></div> Returns: <div class="highlight"><pre><code>{ "created": "2016-10-24T12:21:21.697737+00:00", "id": "01826ff3e4974415afdb2574a7ea5a91", "links": { "files": "https://trng-b2share.eudat.eu/api/files/5594a1bf-1484-4a01-b7d3-f1eb3d2e1dc6", "publication": "https://trng-b2share.eudat.eu/api/records/01826ff3e4974415afdb2574a7ea5a91", "self": "https://trng-b2share.eudat.eu/api/records/01826ff3e4974415afdb2574a7ea5a91/draft", "versions": "https://trng-b2share.eudat.eu/api/records/d855e187e3864ddcaa1b68625866dd78/versions" }, "metadata": { "$schema": "https://trng-b2share.eudat.eu/api/communities/e9b9792e-79fb-4b07-b6b4-b9c2bd06d095/schemas/0#/draft_json_schema", "community": "e9b9792e-79fb-4b07-b6b4-b9c2bd06d095", "community_specific": { "field_1": "value_1", "field_2": "value_2" }, "open_access": true, "owners": [ 8 ], "publication_state": "draft", "titles": [ { "title": "My dataset record" } ] }, "updated": "2016-10-24T12:21:21.697744+00:00" } </code></pre></div> <h5 id="common-errors_1">Common errors<a class="headerlink" href="#common-errors_1" title="Permanent link">#</a></h5> On JSON Patch operation error: <div class="highlight"><pre><code>{ "message": "Invalid Operation.", "errors": [ { "message": "Invalid JSON Pointer" } ], "status": 400 } </code></pre></div> One of the JSON Patch operations is invalid. On JSON Patch content type error: <div class="highlight"><pre><code>{ "message": "Invalid 'Content-Type' header. Expected one of: application/json-patch+json", "status": 415 } </code></pre></div> The supplied content type header value is invalid. On metadata validation error: <div class="highlight"><pre><code>{ "message": "Validation error.", "errors": [ { "message": "{'title': 'Some title'} is not of type 'array'", "field": "titles" } ], "status": 400 } </code></pre></div> The supplied value for the metadata field is invalid. <h4 id="add-externally-referenced-files-to-draft-record">Add externally referenced files to draft record<a class="headerlink" href="#add-externally-referenced-files-to-draft-record" title="Permanent link">#</a></h4> To add files that are located outside of B2SHARE, a reference to that file can be added to a draft record object by defining a list of external references that include a file name and the corresponding EPIC PID. External references are added as normal metadata using a JSON Patch and can only be added during the draft stage. <div class="highlight"><pre><code> HTTP method: PATCH URL path: /api/records/RECORD_ID/draft Required parameters: access_token Payload data: the list of external references provided as a JSON Patch. Status code on success: 200 Returns: informations about the updated metadata of the draft record </code></pre></div> <blockquote> Notes: - you must provide the external references using EPIC PIDs and therefore you need to be able to register new PIDs with an EPIC PID hosting institute using a registered prefix. It is possible to get a prefix through EUDAT, please use the <a href="https://eudat.eu/contact-support-request">contact form</a> for this. </blockquote> Command: <div class="highlight"><pre><code>curl -X PATCH -H 'Accept:application/json-patch+json' -d '["op": "add", "path": "/external_pids", "value": "[{\"ePIC_PID\": \"prefix/suffix-of-file\", \"key\": \"filename\"},{\"ePIC_PID\": \"prefix/suffix-of-file-2\", \"key\": \"filename-2\"}]' "https://$B2SHARE_HOST/api/records/$RECORD_ID/draft?access_token=$ACCESS_TOKEN" </code></pre></div> <h4 id="submit-draft-record-for-publication">Submit draft record for publication<a class="headerlink" href="#submit-draft-record-for-publication" title="Permanent link">#</a></h4> This action marks the draft record as complete and submits it for publication. Currently B2SHARE automatically publishes all the submitted drafts. Please be advised that publishing the draft will make its files immutable. A draft record is submitted for publication if a special metadata field, called ‘publication_state’ is set to ‘submitted’. This field can be set using the <a href="#update-published-record-metadata">metadata update request</a> described above. Depending on the community specification, other fields could be required in order to successfully publish a record. In case one of the required fields is missing the request fails and an error message is returned with further details. <div class="highlight"><pre><code> HTTP method: POST URL path: /api/records/$RECORD_ID/draft Required parameters: access_token Payload data: JSON Patch operation that alters the publication_state metadata field of the record metadata, see example below. Status code on success: 200 </code></pre></div> <blockquote> Notes: - this request is essentially a <a href="#update-published-record-metadata">metadata update request</a> as described above. </blockquote> Command: <div class="highlight"><pre><code>curl -X PATCH -H 'Content-Type:application/json-patch+json' -d '[{"op": "add", "path":"/publication_state", "value": "submitted"}]' "https://$B2SHARE_HOST/api/records/$RECORD_ID/draft?access_token=$ACCESS_TOKEN" </code></pre></div> Returns: <div class="highlight"><pre><code>{ "created": "2016-10-24T12:21:21.697737+00:00", "id": "01826ff3e4974415afdb2574a7ea5a91", "links": { "files": "https://trng-b2share.eudat.eu/api/files/5594a1bf-1484-4a01-b7d3-f1eb3d2e1dc6", "publication": "https://trng-b2share.eudat.eu/api/records/01826ff3e4974415afdb2574a7ea5a91", "versions": "https://trng-b2share.eudat.eu/api/records/c1d28e53db104cb286425902af134579/versions", "self": "https://trng-b2share.eudat.eu/api/records/01826ff3e4974415afdb2574a7ea5a91/draft" }, "metadata": { "$schema": "https://trng-b2share.eudat.eu/api/communities/e9b9792e-79fb-4b07-b6b4-b9c2bd06d095/schemas/0#/draft_json_schema", "DOI": "10.5072/b2share.cdb15c27-326e-4e95-b812-6b1c6b54c299", "community": "e9b9792e-79fb-4b07-b6b4-b9c2bd06d095", "community_specific": {}, "keywords": [ "keyword1", "keyword2" ], "ePIC_PID": "http://hdl.handle.net/11304/2c473f04-d997-47d9-9bdb-d3d71800f870", "open_access": true, "owners": [ 8 ], "publication_state": "published", "titles": [ { "title": "TestRest" } ] }, "updated": "2016-10-24T12:26:51.538025+00:00" } </code></pre></div> <h4 id="update-published-record-metadata">Update published record metadata<a class="headerlink" href="#update-published-record-metadata" title="Permanent link">#</a></h4> This request updates the metadata of an already published record without creating a new version. <div class="highlight"><pre><code> HTTP method: PATCH URL path: /api/records/RECORD_ID/ Required parameters: access_token Payload data: the metadata for the published record object to be updated, in the JSON Patch format (see http://jsonpatch.com/) Status code on success: 200 </code></pre></div> <blockquote> Notes: - The JSON Patch format contains one or more JSONPath strings. The root of these paths are the metadata object, as this is the only mutable object. For instance, to update the title field of the record, use this JSONPath: <code>/titles/title</code> - See the <a href="#update-draft-record-metadata">Update draft record metadata request</a> for examples. </blockquote> <h3 id="record-versioning">Record versioning<a class="headerlink" href="#record-versioning" title="Permanent link">#</a></h3> The following requests concern the versioning of published records. Click on a title to show details. Create new version of published record <h4 id="create-a-new-version-of-an-existing-published-record-into-a-new-draft">Create a new version of an existing published record into a new draft.<a class="headerlink" href="#create-a-new-version-of-an-existing-published-record-into-a-new-draft" title="Permanent link">#</a></h4> <div class="highlight"><pre><code> HTTP method: POST URL path: /api/records/RECORD_ID/draft Required parameters: access_token Status code on success: 201 Returns: the new draft record metadata including new URL location. The metadata will be exactly the same as the original record with the exception of the links and persistent identifiers. Since the new record is in draft state, you can freely alter it, including the files. </code></pre></div> <blockquote> Notes: - the output of the request is the same as the output of the <a href="#create-draft-record">Create new record request</a>. You cannot create a new version of a draft record itself. </blockquote> Command: <div class="highlight"><pre><code>curl -X POST -H "Content-Type:application/json" "https://$B2SHARE_HOST/api/records/$RECORD_ID/draft?access_token=$ACCESS_TOKEN" </code></pre></div> <h4 id="get-all-record-versions">Get all record versions<a class="headerlink" href="#get-all-record-versions" title="Permanent link">#</a></h4> Get all versions of a specific record by using the record head identifier. <div class="highlight"><pre><code> HTTP method: GET URL path: /api/records/RECORD_HEAD_ID/versions Required parameters: None Status code on success: 200 Returns: a JSON structure containing a list of all record versions with identifier, version number and URL. </code></pre></div> <blockquote> Notes: - the record head identifier is not the same as the record identifier. Use the metadata of the record to find the record head identifier, located in the JSONPath <code>/links/versions</code>. - If a record is not versioned, the result will be empty. </blockquote> Command: <div class="highlight"><pre><code>curl -H "Content-Type:application/json" "https://$B2SHARE_HOST/api/records/$RECORD_HEAD_ID/versions" </code></pre></div> Returns: <div class="highlight"><pre><code>{ "versions": [ { "created": "Wed, 05 Jul 2017 09:40:14 GMT", "id": "a766efd2e5d543968fff9dd7bf3783c5", "updated": "Tue, 19 Dec 2017 12:15:06 GMT", "url": "https://trng-b2share.eudat.eu/api/records/a766efd2e5d543968fff9dd7bf3783c5", "version": 1 }, { "created": "Fri, 12 Jan 2018 16:43:33 GMT", "id": "2ff3f5815db3494a840e6b3f1e6a6542", "updated": "Fri, 12 Jan 2018 16:43:33 GMT", "url": "https://trng-b2share.eudat.eu/api/records/2ff3f5815db3494a840e6b3f1e6a6542", "version": 2 } ] } </code></pre></div> On not found error: <div class="highlight"><pre><code>{ "message": "PID is not registered.", "status": 404 } </code></pre></div> <h3 id="other-requests">Other requests<a class="headerlink" href="#other-requests" title="Permanent link">#</a></h3> The following requests are the remaining requests possible in B2SHARE. Click on a title to show details. <h4 id="report-a-record-as-an-abuse-record">Report a record as an abuse record<a class="headerlink" href="#report-a-record-as-an-abuse-record" title="Permanent link">#</a></h4> If there is anything wrong with the record users can report it as an abuse record. An email will be send to the related admin and it will be followed up. There are 4 different reasons listed on the report abuse form and the reporter should choose one of: <ul> <li> Abuse or Inappropriate content </li> <li> Copyrighted material </li> <li> Not research data </li> <li> Illegal content </li> </ul> The reporter can also send a message to explain more about the problem. It is possible for an anonymous user to send the report and authentication is not required. Report an abuse record. <div class="highlight"><pre><code> HTTP method: POST URL path: /api/records/$RECORD_ID/abuse Required parameters: None Payload data: JSON object with information about reporter, the reason indicated by booleans and a message. Status code on success: 200 Returns: a message that an email was sent and the record is reported </code></pre></div> Command: <div class="highlight"><pre><code>curl -X POST -H 'Content-Type:application/json' -d '{"noresearch":true, "abusecontent":false, "copyright":false, "illegalcontent":false,"message":"It is not research data...", "name":"John Smith", "affiliation":"Example University", "email":"j.smith@example.com", "address":"Example street", "city":"Example City", "country":"Example country", "zipcode":"12345", "phone":"7364017452"}' "https://$B2SHARE_HOST/api/records/$RECORD_ID/abuse" </code></pre></div> Payload: <div class="highlight"><pre><code>{ "noresearch": true, "abusecontent": false, "copyright": false, "illegalcontent": false, "message": "It is not research data...", "name": "John Smith", "affiliation": "Example University", "email": "j.smith@example.com", "address": "Example street", "city": "Example City", "country": "Example country", "zipcode": "12345", "phone": "7364017452" } </code></pre></div> Returns: <div class="highlight"><pre><code>{ "message": "The record is reported.", "status": 200 } </code></pre></div> <h4 id="send-record-access-request">Send record access request<a class="headerlink" href="#send-record-access-request" title="Permanent link">#</a></h4> For the records with restricted access to data, a user (either authenticated or anonymous) can send a request to the record owner and ask for it. Send request to access closed data. <div class="highlight"><pre><code> HTTP method: POST URL path: /api/records/$RECORD_ID/accessrequests Required parameters: None Payload data: JSON object with information about who is sending the request Status code on success: 200 Returns: a message that an email was sent </code></pre></div> Command: <div class="highlight"><pre><code>curl -X POST -H 'Content-Type:application/json' -d '{"message":"Explain the request...", "name":"John Smith", "affiliation":"Example University", "email":"j.smith@example.com", "address":"Example street", "city":"Example City", "country":"Example country", "zipcode":"12345", "phone":"7364017452"}' "https://$B2SHARE_HOST/api/records/$RECORD_ID/accessrequests" </code></pre></div> Payload: <div class="highlight"><pre><code>{ "message": "Explain the request...", "name": "John Smith", "affiliation": "Example University", "email": "j.smith@example.com", "address": "Example street", "city": "Example City", "country": "Example country", "zipcode": "12345", "phone": "7364017452" } </code></pre></div> Returns: <div class="highlight"><pre><code>{ "message": "An email was sent to the record owner.", "status": 200 } </code></pre></div> <h4 id="get-record-statistics">Get record statistics<a class="headerlink" href="#get-record-statistics" title="Permanent link">#</a></h4> Returns statistics of a record, indicated by statistic type. Supported statistics: <ul> <li>bucket-file-download-total - total downloads per file in a bucket</li> <li>record-views-total (B2SHARE-v2.2.5) - total number of views for a specific record</li> <li>community-record-views-total (B2SHARE-v2.2.5) - total number of views for records in a community</li> <li>community-file-download-total (B2SHARE-v2.2.5) - total number of downloads for records in a community</li> <li>community-file-size-total (B2SHARE-v2.2.5) - total size of files loaded by a community</li> <li>community-file-amount-total (B2SHARE-v2.2.5) - total number of files loaded by a community</li> </ul> More statistics might be added in future releases of B2SHARE. <div class="highlight"><pre><code> HTTP method: POST URL path: /api/stats Required parameters: None Payload data: JSON structure containing the statistic and required elements for that statistic, see below Status code on success: 200 Returns: JSON structure containing requested statistics </code></pre></div> Command: <div class="highlight"><pre><code>curl -X POST -H 'Content-Type:application/json' -d '<payload>' "https://$B2SHARE_HOST/api/stats" </code></pre></div> Payload examples: <div class="highlight"><pre><code>{"fileDownloads": {"params": {"bucket_id": "b0377611-d5a4-4683-9781-b83edcb86324"}, "stat": "bucket-file-download-total"}} </code></pre></div> <div class="highlight"><pre><code>{"recordViews":{"params":{"pid_value":"a02cfe6e13da458f9dec96c043a4c12a"},"stat":"record-views-total"}} </code></pre></div> <div class="highlight"><pre><code>{"communityRecordViewsTotal":{"params":{"community":"77f140b0-d4aa-437e-80d4-32c0abd3746f"},"stat":"community-record-views-total"}} </code></pre></div> <div class="highlight"><pre><code>{"communityFileDownloadTotal":{"params":{"community":"77f140b0-d4aa-437e-80d4-32c0abd3746f"},"stat":"community-file-download-total"}} </code></pre></div> <div class="highlight"><pre><code>{"communityFileSizeTotal":{"params":{"community":"77f140b0-d4aa-437e-80d4-32c0abd3746f"},"stat":"community-file-size-total"}} </code></pre></div> <div class="highlight"><pre><code>{"communityFileAmountTotal":{"params":{"community":"77f140b0-d4aa-437e-80d4-32c0abd3746f"},"stat":"community-file-amount-total",}} </code></pre></div> Payload: <div class="highlight"><pre><code>{ "fileDownloads": { "params": { "bucket_id": "b0377611-d5a4-4683-9781-b83edcb86324" }, "stat": "bucket-file-download-total" } } </code></pre></div> Returns: <div class="highlight"><pre><code>{ "fileDownloads": { "key_type": "terms", "field": "file_key", "buckets": [ { "value": 1, "key": "file.dat" } ], "type": "bucket" } } </code></pre></div> <h4 id="delete-draft-record">Delete draft record<a class="headerlink" href="#delete-draft-record" title="Permanent link">#</a></h4> Delete a draft record. <div class="highlight"><pre><code> HTTP method: DELETE URL path: /api/records/RECORD_ID/draft Required parameters: access_token Status code on success: 204 Returns: no contents. </code></pre></div> <blockquote> Notes: - you can only delete draft records that you own, not published records. </blockquote> Command: <div class="highlight"><pre><code>curl -X DELETE "https://$B2SHARE_HOST/api/records/$RECORD_ID/draft?access_token=$ACCESS_TOKEN" </code></pre></div> <h4 id="delete-published-record">Delete published record<a class="headerlink" href="#delete-published-record" title="Permanent link">#</a></h4> Delete a published record. <div class="highlight"><pre><code> HTTP method: DELETE URL path: /api/records/RECORD_ID Required parameters: access_token Status code on success: 204 Returns: no contents. </code></pre></div> <blockquote> Notes: - only a site administrator can delete a published record. </blockquote> Command: <div class="highlight"><pre><code>curl -X DELETE "https://$B2SHARE_HOST/api/records/$RECORD_ID/?access_token=$ACCESS_TOKEN" </code></pre></div> <h3 id="support">Support<a class="headerlink" href="#support" title="Permanent link">#</a></h3> Hands-on material is available from the <a href="https://github.com/EUDAT-Training/B2SHARE-Training">EUDAT Training Repository</a>. Our <a href="https://www.eudat.eu/b2share-training-suite">B2SHARE presentations</a> offer training material for the service. Support for B2SHARE and its REST API is available via the EUDAT ticketing system through the <a href="https://eudat.eu/support-request?service=B2SHARE">webform</a>. If you have comments on this page, please submit them through the <a href="http://eudat.eu/support-request?service=DOCUMENTATION">EUDAT support request system</a>.   Last review : 29.1.2025 </article> </div> <script>var target=document.getElementById(location.hash.slice(1));target&&target.name&&(target.checked=target.name.startsWith("__tabbed_"))</script> </div> <button type="button" class="md-top md-icon" data-md-component="top" hidden> <svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 24 24"><path d="M13 20h-2V8l-5.5 5.5-1.42-1.42L12 4.16l7.92 7.92-1.42 1.42L13 8z"/></svg> Back to top </button> </main> <footer class="md-footer"> <div class="md-footer-meta md-typeset"> <div class="md-footer-meta__inner md-grid"> <div class="md-copyright"> <div class="md-copyright__highlight"> This documentation is licensed under <a href='https://creativecommons.org/licenses/by-sa/3.0/legalcode'>CC BY-SA 3.0      <img src='/images/cc-by-sa_icon.png'></a>                                                                                                                </div> </div> <div class="md-social"> <a href="https://gitlab.eudat.eu/sa.apweiler/eudat-documentation" target="_blank" rel="noopener" title="gitlab.eudat.eu" class="md-social__link"> <svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 496 512"><path d="M165.9 397.4c0 2-2.3 3.6-5.2 3.6-3.3.3-5.6-1.3-5.6-3.6 0-2 2.3-3.6 5.2-3.6 3-.3 5.6 1.3 5.6 3.6m-31.1-4.5c-.7 2 1.3 4.3 4.3 4.9 2.6 1 5.6 0 6.2-2s-1.3-4.3-4.3-5.2c-2.6-.7-5.5.3-6.2 2.3m44.2-1.7c-2.9.7-4.9 2.6-4.6 4.9.3 2 2.9 3.3 5.9 2.6 2.9-.7 4.9-2.6 4.6-4.6-.3-1.9-3-3.2-5.9-2.9M244.8 8C106.1 8 0 113.3 0 252c0 110.9 69.8 205.8 169.5 239.2 12.8 2.3 17.3-5.6 17.3-12.1 0-6.2-.3-40.4-.3-61.4 0 0-70 15-84.7-29.8 0 0-11.4-29.1-27.8-36.6 0 0-22.9-15.7 1.6-15.4 0 0 24.9 2 38.6 25.8 21.9 38.6 58.6 27.5 72.9 20.9 2.3-16 8.8-27.1 16-33.7-55.9-6.2-112.3-14.3-112.3-110.5 0-27.5 7.6-41.3 23.6-58.9-2.6-6.5-11.1-33.3 2.6-67.9 20.9-6.5 69 27 69 27 20-5.6 41.5-8.5 62.8-8.5s42.8 2.9 62.8 8.5c0 0 48.1-33.6 69-27 13.7 34.7 5.2 61.4 2.6 67.9 16 17.7 25.8 31.5 25.8 58.9 0 96.5-58.9 104.2-114.8 110.5 9.2 7.9 17 22.9 17 46.4 0 33.7-.3 75.4-.3 83.6 0 6.5 4.6 14.4 17.3 12.1C428.2 457.8 496 362.9 496 252 496 113.3 383.5 8 244.8 8M97.2 352.9c-1.3 1-1 3.3.7 5.2 1.6 1.6 3.9 2.3 5.2 1 1.3-1 1-3.3-.7-5.2-1.6-1.6-3.9-2.3-5.2-1m-10.8-8.1c-.7 1.3.3 2.9 2.3 3.9 1.6 1 3.6.7 4.3-.7.7-1.3-.3-2.9-2.3-3.9-2-.6-3.6-.3-4.3.7m32.4 35.6c-1.6 1.3-1 4.3 1.3 6.2 2.3 2.3 5.2 2.6 6.5 1 1.3-1.3.7-4.3-1.3-6.2-2.2-2.3-5.2-2.6-6.5-1m-11.4-14.7c-1.6 1-1.6 3.6 0 5.9s4.3 3.3 5.6 2.3c1.6-1.3 1.6-3.9 0-6.2-1.4-2.3-4-3.3-5.6-2"/></svg> </a> </div> </div> </div> </footer> </div> <div class="md-dialog" data-md-component="dialog"> <div class="md-dialog__inner md-typeset"></div> </div> <script id="__config" type="application/json">{"base": "../..", "features": ["navigation.sections", "navigation.tabs", "navigation.top", "toc.integrate", "search.suggest"], "search": "../../assets/javascripts/workers/search.f8cc74c7.min.js", "translations": {"clipboard.copied": "Copied to clipboard", "clipboard.copy": "Copy to clipboard", "search.result.more.one": "1 more on this page", "search.result.more.other": "# more on this page", "search.result.none": "No matching documents", "search.result.one": "1 matching document", "search.result.other": "# matching documents", "search.result.placeholder": "Type to start searching", "search.result.term.missing": "Missing", "select.version": "Select version"}}</script> <script src="../../assets/javascripts/bundle.f1b6f286.min.js"></script> </body> </html>

CINXE.COM

HTTP REST API - EUDAT Documentation