CINXE.COM
Datasets API Quick Start Guide Mendeley Developer Portal
<!DOCTYPE html> <!--[if lt IE 8 ]> <html lang="en" class="no-js ie ie7 no-js"> <![endif]--> <!--[if lt IE 9 ]> <html lang="en" class="no-js ie ie8 no-js"> <![endif]--> <!--[if lt IE 10 ]> <html lang="en" class="no-js ie ie9 no-js"> <![endif]--> <!--[if (gt IE 9)|!(IE)]><!--> <html lang="en" class="no-js"> <!--<![endif]--> <head> <meta charset="utf-8"> <meta http-equiv="X-UA-Compatible" content="IE=edge"> <meta name="viewport" content="width=device-width, initial-scale=1"> <meta name="description" content=""> <link rel="shortcut icon" href="images/favicon-2.ico"> <link href="//maxcdn.bootstrapcdn.com/font-awesome/4.2.0/css/font-awesome.min.css" rel="stylesheet"> <link rel="stylesheet" href="/fonts/font-mfizz-1.2/font-mfizz.css"> <title>Datasets API Quick Start Guide Mendeley Developer Portal</title> <!-- OneTrust Cookies Consent Banner --> <script src="https://cdn.cookielaw.org/scripttemplates/otSDKStub.js" type="text/javascript" charset="UTF-8" data-domain-script="bfc52c48-f7c5-45a4-a7e0-e44db83eeff9"></script> <!-- OneTrust Cookies Consent Notice end --> <script src="/bower/es5-shim/es5-shim.min.js"></script> <script src="/bower/html5shiv/dist/html5shiv.min.js"></script> <script src="//ajax.googleapis.com/ajax/libs/jquery/1.11.1/jquery.min.js"></script> <script src="/bower/bootstrap/js/dropdown.js"></script> <script src="/bower/bootstrap/js/collapse.js"></script> <script data-main="../js/config" src="../bower/requirejs/require.js"></script> <script src="https://ajax.googleapis.com/ajax/libs/webfont/1.4.7/webfont.js"></script> <script> WebFont.load({ google: { families: ["Merriweather:300,400,700,900", "Open Sans:300,300italic,400,400italic,600,600italic,700,700italic,800,800italic"] } }); </script> <script> $(function () { $("#page-header").load("../header.html"); $("#page-footer").load("../footer.html"); }); </script> <!-- Bootstrap core CSS --> <link href="/css/screen.css" rel="stylesheet"> <script src="https://ajax.googleapis.com/ajax/libs/jquery/1.12.0/jquery.min.js"></script> <script type="text/javascript"> window.mendeley = {}; require(['config'], function (appConfig) { appConfig.getAdobeLaunchScriptTag(); }); </script> </head> <body id="quick-start-guides"> <!-- header loaded externally --> <div id="page-header"> </div> <!-- Main Content START --> <section class="section-freetext section-introtext"> <div class="container"> <div class="row"> <h2 class="col-md-12 title">Datasets API Quick Start Guides</h2> <p>Here are some guick start quides and code snippets to show you the capabilities of some of the datasets APIs.</p> </div> </div> </section> <section class="long-page-section"> <div class="container"> <div class="row"> <p>Datasets published on <a href="https://data.mendeley.com/">Mendeley Data</a> are available through the Datasets API. A dataset is a collection of research data files, alongside some metadata about the dataset itself. You can create and edit a private draft dataset, but once published, it becomes a permanent unchanging public record. Once published, it can be referenced from other sources using its DOI, which is made up of the dataset鈥檚 unique identifier (e.g. <code>322y43x9b7</code>) and its version (e.g. <code>1</code>).</p> <p>In the following examples, we will assume you have already retrieved an OAuth token to grant access to Mendeley APIs. Wherever you see <code>$TOKEN</code> in these examples, you should substitute your own OAuth token.</p> </div> <div class="row"> <h4>Retrieve the ids of published datasets</h4> <p>By default the API returns a list of dataset ids. </p> <p><a href="#demo-1" data-toggle="collapse">See steps involved</a></p> <div id="demo-1" class="collapse"> <pre><code>curl -X GET "https://api.mendeley.com/datasets" -H "Authorization: Bearer $TOKEN" -H "Accept: application/vnd.mendeley-public-dataset.1+json" </code></pre> </div> <h4>Retrieving a dataset by id</h4> <p>You can retrieve full details of a published dataset using its id (<code>xrpfs4r78h</code> in the following example). </p> <p><a href="#demo-2" data-toggle="collapse">See steps involved</a></p> <div id="demo-2" class="collapse"> <pre><code>curl -X GET "https://api.mendeley.com/datasets/xrpfs4r78h" -H "Authorization: Bearer $TOKEN" -H "Accept: application/vnd.mendeley-public-dataset.1+json" </code></pre> <p>This dataset has multiple published versions. By default, the latest version is returned. You can retrieve a specific version by adding a <code>version</code> query parameter: </p> <pre><code>curl -X GET "https://api.mendeley.com/datasets/xrpfs4r78h?version=2" -H "Authorization: Bearer $TOKEN" -H "Accept: application/vnd.mendeley-public-dataset.1+json" </code></pre> </div> <h4>Avoiding multiple API calls</h4> <p>By default, the API returns only the id for each published dataset. You can avoid querying the API again to retrieve more details by specifying the fields you would like. </p> <p><a href="#demo-3" data-toggle="collapse">See steps involved</a></p> <div id="demo-3" class="collapse"> <pre><code>curl -X GET "https://api.mendeley.com/datasets?fields=results.id,results.version,results.name" -H "Authorization: Bearer $TOKEN" -H "Accept: application/vnd.mendeley-public-dataset.1+json" </code></pre> <p>Fields can be extracted from deep inside the dataset structure. This retrieves the last names of all contributors:</p> <pre><code>curl -X GET "https://api.mendeley.com/datasets?fields=results.name,results.contributors.last_name" -H "Authorization: Bearer $TOKEN" -H "Accept: application/vnd.mendeley-public-dataset.1+json" </code></pre> <p>Using a <code>*</code> at any level returns all fields below that level. You can use this to retrieve all dataset fields. This can result in large responses, so it鈥檚 better to retrieve just the fields you need.</p> <pre><code>curl -X GET "https://api.mendeley.com/datasets?fields=results.*" -H "Authorization: Bearer $TOKEN" -H "Accept: application/vnd.mendeley-public-dataset.1+json" </code></pre> </div> <h4>Searching for datasets linked to an article or a journal</h4> <p>You can find datasets linked to an article if you have the article DOI (<code>10.1093/nc/niv009</code> in this example). </p> <p><a href="#demo-5" data-toggle="collapse">See steps involved</a></p> <div id="demo-5" class="collapse"> <p>Note that the DOI, as for all other query parameters, needs to be URL-escaped. That is, characters with a special meaning in a URL should be replaced with <code>%xx</code>, where <code>xx</code> are the hexadecimal representation of the ASCII value of the character. </p> <pre><code>curl -X GET "https://api.mendeley.com/datasets?article_doi=10.1093%2Fnc%2Fniv009" -H "Authorization: Bearer $TOKEN" -H "Accept: application/vnd.mendeley-public-dataset.1+json" </code></pre> <p>You can find datasets linked to a journal if you have the journal ISSN (<code>2057-2107</code> in this example). </p> <pre><code>curl -X GET "https://api.mendeley.com/datasets?issn=2057-2107" -H "Authorization: Bearer $TOKEN" -H "Accept: application/vnd.mendeley-public-dataset.1+json" </code></pre> </div> <h4>Creating a new dataset</h4> <p>A dataset is created in draft form. The draft can be edited until it is published. A draft dataset includes the version and DOI it will have when published, but the DOI is not registered (and therefore cannot be used to find the dataset) until the dataset is published. </p> <p><a href="#demo-6" data-toggle="collapse">See steps involved</a></p> <div id="demo-6" class="collapse"> <p>The only mandatory field for a new draft is the name, but most fields are mandatory for publishing. So, to create a new minimal dataset, we can do: </p> <pre><code>curl -X POST "https://api.mendeley.com/datasets/drafts" -H "Authorization: Bearer $TOKEN" -H "Accept: application/vnd.mendeley-draft-dataset.1+json" -H "Content-Type: application/vnd.mendeley-dataset-creation-request.1+json" -d '{"name":"My dataset"}' </code></pre> </div> <h4>Editing a draft</h4> <p>Editing a draft (with id <code>b7nzjm7m3r</code> in this example) involves specifying replacement values for the fields you want to update. You can update multiple fields in the same request. This example updates the description and the licence of the dataset. </p> <p><a href="#demo-7" data-toggle="collapse">See steps involved</a></p> <div id="demo-7" class="collapse"> <pre><code>curl -X PATCH "https://api.mendeley.com/datasets/drafts/b7nzjm7m3r" -H "Authorization: Bearer $TOKEN" -H "Accept: application/vnd.mendeley-draft-dataset.1+json" -H "Content-Type: application/vnd.mendeley-dataset-patch.1+json" -d '{"description":"A dataset created via the Mendeley API.", "data_licence":{"id":"126f78a3-08e2-42f2-a226-db28838adc93"}}' </code></pre> </div> <h4>Adding files</h4> <p>Adding files is a special case of editing a draft. Mendeley has a separate API for uploading files. You POST the file鈥檚 binary content and receive an identifier that can be used to attach the file to the draft. </p> <p> <a href="#demo-8" data-toggle="collapse">See steps involved</a></p> <div id="demo-8" class="collapse"> <p>To upload a file (<code>my-data.xls</code> in this example), you should POST the file contents along with its <code>Content-Type</code>: </p> <pre><code>curl -X POST "https://api.mendeley.com/file_content" -H "Authorization: Bearer $TOKEN" -H "Accept: application/vnd.mendeley-content-ticket.1+json" -H "Content-Type: application/vnd.ms-excel" --data-binary @my-data.xls </code></pre> <p>Make note of the <code>id</code> in the JSON this returns. You will need this to add the file to the dataset. In this example we鈥檝e assumed the id is <code>cbc3b164-6743-4596-99a1-9644dc714b60</code>:</p> <pre><code>curl -X PATCH "https://api.mendeley.com/datasets/drafts/b7nzjm7m3r" -H "Authorization: Bearer $TOKEN" -H "Accept: application/vnd.mendeley-draft-dataset.1+json" -H "Content-Type: application/vnd.mendeley-dataset-patch.1+json" -d '{"files":[{"filename":"my-data.xls","description":"My data","content_details":{"id":"cbc3b164-6743-4596-99a1-9644dc714b60"}}]}' </code></pre> <p><code>files</code> is an array, so you can attach multiple files to the dataset in a single PATCH operation.</p> </div> <h4>Sharing a draft dataset</h4> <p>Draft datasets are private and can only be accessed by their creator. The creator can allow other people to view (but not edit) the draft by giving them the value stored in the <code>access_code</code> field.</p> <p> <a href="#demo-9" data-toggle="collapse">See steps involved</a></p> <div id="demo-9" class="collapse"> <p>You can retrieve someone else鈥檚 draft (<code>3dyfw2py9d</code> in this example) using their access code (<code>cf78b5ea-ea5d-4d55-9901-2163ccf958ce</code> in this example). </p> <pre><code>curl -X GET "https://api.mendeley.com/datasets/drafts/3dyfw2py9d?access_code=cf78b5ea-ea5d-4d55-9901-2163ccf958ce" -H "Authorization: Bearer $TOKEN" -H "Accept: application/vnd.mendeley-draft-dataset.1+json" </code></pre> <p>When the draft is published, the new draft version will have a different access code.</p> </div> <h4>Publishing a dataset</h4> <p>There is an API call that allows you to publish a draft dataset (<code>b7nzjm7m3r</code> in this example).</p> <p> <a href="#demo-10" data-toggle="collapse">See steps involved</a></p> <div id="demo-10" class="collapse"> <pre><code>curl -X POST "https://api.mendeley.com/datasets/drafts/b7nzjm7m3r" -H "Authorization: Bearer $TOKEN" -H "Accept: application/vnd.mendeley-content-ticket.1+json" </code></pre> <p>After publishing, you can continue to edit your draft, but it will now have a higher version number, a different provisional DOI and a new access code.</p> <p>Several fields that are optional while editing a draft dataset are mandatory for publishing. If your dataset is not suitable for publishing you will receive an error response like this.</p> <pre><code> { "message": "This dataset has errors that prevent you publishing it", "field_errors": [ { "field": "description", "message": "Dataset should have a description" }, { "field": "categories", "message": "Dataset should have at least one category" }, { "field": "files", "message": "Dataset should contain at least one file" } ] } </code></pre> <p>Once the error for each listed field in the JSON has been resolved, you will be able to publish the draft.</p> </div> <h4>Publishing data under embargo</h4> <p>Datasets can be published under embargo. This involves setting an embargo date on the draft. When the draft is published, it will be under embargo until the date you鈥檝e specified, and only very limited information about it will be available (currently the name of the dataset, its DOI and the embargo date). </p> <p><a href="#demo-11" data-toggle="collapse">See steps involved</a> </p> <div id="demo-11" class="collapse"> <pre><code>curl -X PATCH "https://api.mendeley.com/datasets/drafts/b7nzjm7m3r" -H "Authorization: Bearer $TOKEN" -H "Accept: application/vnd.mendeley-draft-dataset.1+json" -H "Content-Type: application/vnd.mendeley-dataset-patch.1+json" -d '{"embargo_date":"2020-01-01T00:00:00Z"}' </code></pre> <p>To remove the embargo from a draft, set an embargo date in the past. </p> </div> <br> <br> <br> <br> <br> <br> </div> </section> <!-- Main Content: END --> <!-- footer loaded externally --> <div id="page-footer"> </div> <script src="../js/adobe-analytics.js" type="text/javascript"> </script> </body> </html> <!-- / dinah -->