Mercurial > hg > LGDataverses
view DVN-web/installer/dvninstall/doc/guides/dataverse-api-main.html @ 6:1b2188262ae9
adding the installer.
| author | "jurzua <jurzua@mpiwg-berlin.mpg.de>" |
|---|---|
| date | Wed, 13 May 2015 11:50:21 +0200 |
| parents | |
| children |
line wrap: on
line source
<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd"> <html xmlns="http://www.w3.org/1999/xhtml"> <head> <meta http-equiv="Content-Type" content="text/html; charset=utf-8" /> <title>APIs Guide — The Harvard Dataverse Network 3.6.1 documentation</title> <link rel="stylesheet" href="_static/agogo.css" type="text/css" /> <link rel="stylesheet" href="_static/pygments.css" type="text/css" /> <script type="text/javascript"> var DOCUMENTATION_OPTIONS = { URL_ROOT: './', VERSION: '3.6.1', COLLAPSE_INDEX: false, FILE_SUFFIX: '.html', HAS_SOURCE: true }; </script> <script type="text/javascript" src="_static/jquery.js"></script> <script type="text/javascript" src="_static/underscore.js"></script> <script type="text/javascript" src="_static/doctools.js"></script> <script type="text/javascript" src="http://cdn.mathjax.org/mathjax/latest/MathJax.js?config=TeX-AMS-MML_HTMLorMML"></script> <link rel="top" title="The Harvard Dataverse Network 3.6.1 documentation" href="index.html" /> <link rel="prev" title="DVN Developers Guide" href="dataverse-developer-main.html" /> </head> <body> <div class="header-wrapper"> <div class="header"> <div class="headertitle"><a href="index.html">The Harvard Dataverse Network 3.6.1 documentation</a></div> <div class="rel"> <a href="dataverse-developer-main.html" title="DVN Developers Guide" accesskey="P">previous</a> | <a href="genindex.html" title="General Index" accesskey="I">index</a> </div> </div> </div> <div class="content-wrapper"> <div class="content"> <div class="document"> <div class="documentwrapper"> <div class="bodywrapper"> <div class="body"> <div class="section" id="apis-guide"> <h1>APIs Guide<a class="headerlink" href="#apis-guide" title="Permalink to this headline">¶</a></h1> <p id="api"><strong>Introduction</strong></p> <p>We strongly encourage anyone interested in building tools to interoperate with the Dataverse Network to utilize our open source APIs. Please visit our <a class="reference external" href="http://thedata.org/book/apps">website</a> for examples of external apps that have been built to work with our APIs.</p> <div class="section" id="data-sharing-api"> <span id="id1"></span><h2>Data Sharing API<a class="headerlink" href="#data-sharing-api" title="Permalink to this headline">¶</a></h2> <p>As of version 3.0, a new API for programmatic access to the DVN data and metadata has been added. The API allows a remote, non-DVN archive/application to search the holdings and download files from a Dataverse Network.</p> <p>The Data Sharing API documentation is available below:</p> <div class="section" id="api-urls"> <h3>API URLs<a class="headerlink" href="#api-urls" title="Permalink to this headline">¶</a></h3> <p>The URLs for the Data Sharing API resources are of the form:</p> <p><tt class="docutils literal"><span class="pre">/dvn/api/{/arg}{?{{arg}&...}}</span></tt></p> <p>Generally, mandatory arguments are embedded in the URL and optional arguments are supplied as query parameters, in the <tt class="docutils literal"><span class="pre">?param=...</span></tt> notation. See the documentation for the individual resources below for details.</p> <p>The API supports basic HTTP Authentication. So that the access credentials are not transmitted in the clear, the API verbs (methods) below are <strong>only accessible over HTTPS</strong>.</p> </div> <div class="section" id="metadata-api"> <h3>Metadata API<a class="headerlink" href="#metadata-api" title="Permalink to this headline">¶</a></h3> <p>The API for accessing Dataverse Network metadata is implemented in 4 verbs (resources):</p> <div class="line-block"> <div class="line"><tt class="docutils literal"><span class="pre">metadataSearchFields</span></tt></div> <div class="line"><tt class="docutils literal"><span class="pre">metadataSearch</span></tt></div> <div class="line"><tt class="docutils literal"><span class="pre">metadataFormatsAvailable</span></tt></div> <div class="line"><tt class="docutils literal"><span class="pre">metadata</span></tt></div> </div> <div class="section" id="metadatasearchfields"> <h4>metadataSearchFields<a class="headerlink" href="#metadatasearchfields" title="Permalink to this headline">¶</a></h4> <p><strong>Arguments:</strong></p> <p><tt class="docutils literal"><span class="pre">none</span></tt></p> <p><strong>URL example:</strong></p> <p><tt class="docutils literal"><span class="pre">/dvn/api/metadataSearchFields/</span></tt></p> <p><strong>Output:</strong></p> <p>XML record in the format below:</p> <div class="highlight-guess"><div class="highlight"><pre><span class="nt"><MetadataSearchFields></span> <span class="nt"><SearchableField></span> <span class="nt"><fieldName></span>title<span class="nt"></fieldName></span> <span class="nt"><fieldDescription></span>title<span class="nt"></fieldDescription></span> <span class="nt"></SearchableField></span> <span class="nt"><SearchableField></span> <span class="nt"><fieldName></span>authorName<span class="nt"></fieldName></span> <span class="nt"><fieldDescription></span>authorName<span class="nt"></fieldDescription></span> <span class="nt"></SearchableField></span> <span class="nt"><SearchableField></span> <span class="nt"><fieldName></span>otherId<span class="nt"></fieldName></span> <span class="nt"><fieldDescription></span>otherId<span class="nt"></fieldDescription></span> <span class="nt"></SearchableField></span> ... <span class="nt"></MetadataSearchableFields></span> </pre></div> </div> </div> <div class="section" id="metadatasearch"> <h4>metadataSearch<a class="headerlink" href="#metadatasearch" title="Permalink to this headline">¶</a></h4> <p><strong>Arguments:</strong></p> <div class="line-block"> <div class="line"><tt class="docutils literal"><span class="pre">queryString:</span> <span class="pre">mandatory,</span> <span class="pre">embedded.</span></tt></div> <div class="line"><em>Standard Lucene-style search queries are supported; (same query format currently used to define OAI sets, etc.)</em></div> </div> <p><strong>URLs examples:</strong></p> <div class="line-block"> <div class="line"><tt class="docutils literal"><span class="pre">/dvn/api/metadataSearch/title:test</span></tt></div> <div class="line"><tt class="docutils literal"><span class="pre">/dvn/api/metadataSearch/title:test</span> <span class="pre">AND</span> <span class="pre">authorName:leonid</span></tt></div> </div> <p><strong>Output:</strong></p> <p>XML record in the format below:</p> <div class="highlight-guess"><div class="highlight"><pre><span class="nt"><MetadataSearchResults></span> <span class="nt"><searchQuery></span>title:test<span class="nt"></searchQuery></span> <span class="nt"><searchHits></span> <span class="nt"><study</span> <span class="na">ID=</span><span class="s">"hdl:TEST/10007"</span><span class="nt">/></span> ... <span class="nt"></searchHits></span> <span class="nt"></MetadataSearchResults></span> </pre></div> </div> <p><strong>Error Conditions:</strong></p> <p>Note that when the query does not produce any results, the resource returns an XML record with an empty <tt class="docutils literal"><span class="pre"><searchHits></span></tt> list, NOT a 404.</p> </div> <div class="section" id="metadataformatsavailable"> <h4>metadataFormatsAvailable<a class="headerlink" href="#metadataformatsavailable" title="Permalink to this headline">¶</a></h4> <p><strong>Arguments:</strong></p> <div class="line-block"> <div class="line"><tt class="docutils literal"><span class="pre">objectId:</span> <span class="pre">mandatory,</span> <span class="pre">embedded.</span></tt></div> <div class="line"><em>Both global and local (database) IDs are supported.</em></div> </div> <p><strong>URLs examples:</strong></p> <div class="line-block"> <div class="line"><tt class="docutils literal"><span class="pre">/dvn/api/metadataFormatsAvailable/hdl:1902.1/6635</span></tt></div> <div class="line"><tt class="docutils literal"><span class="pre">/dvn/api/metadataFormatsAvailable/9956</span></tt></div> </div> <p><strong>Output:</strong></p> <p>XML record in the format below:</p> <div class="highlight-guess"><div class="highlight"><pre><span class="nt"><MetadataFormatsAvailable</span> <span class="na">studyId=</span><span class="s">"hdl:TEST/10007"</span><span class="nt">></span> <span class="nt"><formatAvailable</span> <span class="na">selectSupported=</span><span class="s">"true"</span> <span class="na">excludeSupported=</span><span class="s">"true"</span><span class="nt">></span> <span class="nt"><formatName></span>ddi<span class="nt"></formatName></span> <span class="nt"><formatSchema></span>http://www.icpsr.umich.edu/DDI/Version2-0.xsd<span class="nt"></formatSchema></span> <span class="nt"><formatMime></span>application/xml<span class="nt"></formatMime></span> <span class="nt"></formatAvailable></span> <span class="nt"><formatAvailable></span> <span class="nt"><formatName></span>oai_dc<span class="nt"></formatName></span> <span class="nt"><formatSchema></span>http://www.openarchives.org/OAI/2.0/oai_dc.xsd<span class="nt"></formatSchema></span> <span class="nt"><formatMime></span>application/xml<span class="nt"></formatMime></span> <span class="nt"></formatAvailable></span> <span class="nt"></MetadataFormatsAvailable></span> </pre></div> </div> <p>(<strong>Note</strong> the <tt class="docutils literal"><span class="pre">selectSupported</span></tt> and <tt class="docutils literal"><span class="pre">excludeSupported</span></tt> attributes above!)</p> <p><strong>Error Conditions:</strong></p> <p><tt class="docutils literal"><span class="pre">404</span> <span class="pre">NOT</span> <span class="pre">FOUND</span></tt> if study does not exist</p> </div> <div class="section" id="metadata"> <h4>metadata<a class="headerlink" href="#metadata" title="Permalink to this headline">¶</a></h4> <p><strong>Arguments:</strong></p> <div class="line-block"> <div class="line"><tt class="docutils literal"><span class="pre">objectId:</span> <span class="pre">mandatory,</span> <span class="pre">embedded.</span></tt></div> <div class="line"><em>Both global and local (database) IDs are supported.</em></div> </div> <div class="line-block"> <div class="line"><tt class="docutils literal"><span class="pre">formatType:</span> <span class="pre">optional,</span> <span class="pre">query.</span></tt></div> <div class="line"><em>Defaults to DDI if not supplied.</em></div> </div> <p><strong>URLs examples:</strong></p> <div class="line-block"> <div class="line"><tt class="docutils literal"><span class="pre">/dvn/api/metadata/hdl:1902.1/6635</span> <span class="pre">/dvn/api/metadata/9956</span></tt></div> <div class="line"><tt class="docutils literal"><span class="pre">/dvn/api/metadata/hdl:1902.1/6635?formatType=ddi</span></tt></div> </div> <p><strong>Output:</strong></p> <p>Metadata record in the format requested, if available. No extra headers, etc.</p> <p><strong>Partial selection of metadata sections:</strong></p> <p>When requesting partial records is supported (see <tt class="docutils literal"><span class="pre">metadataFormatsAvailable</span></tt>, above for more info), these additional parameters can be supplied:</p> <div class="line-block"> <div class="line"><tt class="docutils literal"><span class="pre">partialExclude:</span> <span class="pre">optional,</span> <span class="pre">query.</span></tt></div> <div class="line"><em>Xpath query representing metadata section to drop, where supported.</em></div> </div> <div class="line-block"> <div class="line"><tt class="docutils literal"><span class="pre">partialInclude:</span> <span class="pre">optional,</span> <span class="pre">query.</span></tt></div> <div class="line"><em>Xpath query representing metadata section to include, where supported.</em></div> </div> <p><strong>Examples:</strong></p> <div class="line-block"> <div class="line"><tt class="docutils literal"><span class="pre">/dvn/api/metadata/hdl:1902.1/6635?formatType=ddi&partialExclude=codeBook/dataDscr</span></tt></div> <div class="line">will produce a DDI without the dataDscr section.</div> <div class="line"><em>[I’m expecting this to be the single most useful and common real-life application of thisfeature - L.A.]</em></div> </div> <div class="line-block"> <div class="line"><tt class="docutils literal"><span class="pre">/dvn/api/metadata/hdl:1902.1/6635?formatType=ddi&partialInclude=codeBook/stdyDscr</span></tt></div> <div class="line">will produce a DDI with the stdyDscr section only.</div> </div> <p>(<strong>Note</strong>: for now, only simple top-level Xpath queries like the above are supported).</p> <p>One other limitation of the current implementation: it does not validate the supplied <tt class="docutils literal"><span class="pre">partialExclude</span></tt> and <tt class="docutils literal"><span class="pre">partialInclude</span></tt> arguments; no error messages/diagnostics will be given if the Xpath queries are not part of the metadata schema. For example, if you request partialInclude=foobar, it will quietly produce an empty DDI, and <tt class="docutils literal"><span class="pre">partialExclude=foobar</span></tt> will not exclude anything (and you will get a complete DDI).</p> <p><strong>Error Conditions:</strong></p> <div class="line-block"> <div class="line"><tt class="docutils literal"><span class="pre">404</span> <span class="pre">NOT</span> <span class="pre">FOUND</span></tt></div> <div class="line">if study does not exist</div> </div> <div class="line-block"> <div class="line"><tt class="docutils literal"><span class="pre">503</span> <span class="pre">SERVICE</span> <span class="pre">UNAVAILABLE</span></tt></div> <div class="line">if study exists, but the format requested is not available;</div> <div class="line">also, when partial exclude or include is requested, if it’s not supported by the service (see the documenation for metadataFormatsAvailable above).</div> </div> <p><strong>Notes:</strong></p> <p>A real-life workflow scenario may go as follows:</p> <ol class="loweralpha simple"> <li>Find the searchable index fields on this DVN (meatadataSearchFields)</li> <li>Run a search (metadataSearch)</li> <li>For [select] studies returned, find what metadata formats are available (metadataFormatsAvailable)</li> <li>Retrieve the metadata in the desired format (metadata)</li> </ol> </div> </div> <div class="section" id="file-access-api"> <h3>File Access API<a class="headerlink" href="#file-access-api" title="Permalink to this headline">¶</a></h3> <p>The Dataverse Network API for downloading digital objects (files) is implemented in 2 verbs (resources):</p> <div class="line-block"> <div class="line"><tt class="docutils literal"><span class="pre">downloadInfo</span></tt></div> <div class="line"><tt class="docutils literal"><span class="pre">download</span></tt></div> </div> <div class="section" id="downloadinfo"> <h4>downloadInfo<a class="headerlink" href="#downloadinfo" title="Permalink to this headline">¶</a></h4> <p><strong>Arguments:</strong></p> <div class="line-block"> <div class="line"><tt class="docutils literal"><span class="pre">objectId:</span> <span class="pre">mandatory,</span> <span class="pre">embedded.</span></tt></div> <div class="line">Database ID of the Dataverse Network Study File.</div> </div> <p><strong>URLs example:</strong></p> <p><tt class="docutils literal"><span class="pre">/dvn/api/downloadInfo/9956</span></tt></p> <p><strong>Output:</strong></p> <p>XML record in the format below:</p> <p><em>(Note: the record below is only an example; we will provide full schema/documentation of theFileDownloadInfo record format below)</em></p> <div class="highlight-guess"><div class="highlight"><pre><span class="nt"><FileDownloadInfo></span> <span class="nt"><studyFile</span> <span class="na">fileId=</span><span class="s">"9956"</span><span class="nt">></span> <span class="nt"><fileName></span>prettypicture.jpg<span class="nt"></fileName></span> <span class="nt"><fileMimeType></span>image/jpeg<span class="nt"></fileMimeType></span> <span class="nt"><fileSize></span>52825<span class="nt"></fileSize></span> <span class="nt"><Authentication></span> <span class="nt"><authUser></span>testUser<span class="nt"></authUser></span> <span class="nt"><authMethod></span>password<span class="nt"></authMethod></span> <span class="nt"></Authentication></span> <span class="nt"><Authorization</span> <span class="na">directAccess=</span><span class="s">"true"</span><span class="nt">/></span> <span class="nt"><accessPermissions</span> <span class="na">accessGranted=</span><span class="s">"true"</span><span class="nt">></span>Authorized Access only<span class="nt"></accessPermissions></span> <span class="nt"><accessRestrictions</span> <span class="na">accessGranted=</span><span class="s">"true"</span><span class="nt">></span>Terms of Use<span class="nt"></accessRestrictions></span> <span class="nt"><accessServicesSupported></span> <span class="nt"><accessService></span> <span class="nt"><serviceName></span>thumbnail<span class="nt"></serviceName></span> <span class="nt"><serviceArgs></span>imageThumb=true<span class="nt"></serviceArgs></span> <span class="nt"><contentType></span>image/png<span class="nt"></contentType></span> <span class="nt"><serviceDesc></span>Image Thumbnail<span class="nt"></serviceDesc></span> <span class="nt"></accessService></span> <span class="nt"></accessServicesSupported></span> <span class="nt"></studyFile></span> <span class="nt"></FileDownloadInfo></span> </pre></div> </div> <p><strong>Error Conditions:</strong></p> <div class="line-block"> <div class="line"><tt class="docutils literal"><span class="pre">404</span> <span class="pre">NOT</span> <span class="pre">FOUND</span></tt></div> <div class="line">Study file does not exist.</div> </div> </div> <div class="section" id="download"> <h4>download<a class="headerlink" href="#download" title="Permalink to this headline">¶</a></h4> <p><strong>Arguments:</strong></p> <div class="line-block"> <div class="line"><tt class="docutils literal"><span class="pre">objectId:</span> <span class="pre">mandatory,</span> <span class="pre">embedded.</span></tt></div> <div class="line">Database ID of the DVN Study File.</div> </div> <div class="line-block"> <div class="line"><tt class="docutils literal"><span class="pre">Optional</span> <span class="pre">Query</span> <span class="pre">args:</span></tt></div> <div class="line">As specified in the output of downloadInfo, above.</div> </div> <p><strong>URLs examples:</strong></p> <div class="line-block"> <div class="line"><tt class="docutils literal"><span class="pre">/dvn/api/download/9956</span></tt></div> <div class="line"><tt class="docutils literal"><span class="pre">/dvn/api/download/9956?imageThumb=true</span></tt></div> <div class="line"><tt class="docutils literal"><span class="pre">/dvn/api/download/9957?fileFormat=stata</span></tt></div> </div> <p><strong>Output:</strong></p> <p>Byte Stream (with proper HTTP headers specifying the content type, file name and such)</p> <p><strong>Error Conditions:</strong></p> <div class="line-block"> <div class="line"><tt class="docutils literal"><span class="pre">404</span> <span class="pre">NOT</span> <span class="pre">FOUND</span></tt></div> <div class="line">Study file does not exist.</div> </div> <div class="line-block"> <div class="line"><tt class="docutils literal"><span class="pre">401</span> <span class="pre">AUTHORIZATION</span> <span class="pre">REQUIRED</span></tt></div> <div class="line">Access to restricted object attempted without HTTP Authorization header supplied.</div> </div> <div class="line-block"> <div class="line"><tt class="docutils literal"><span class="pre">403</span> <span class="pre">PERMISSION</span> <span class="pre">DENIED</span> <span class="pre">HTTP</span></tt></div> <div class="line">Authorization header supplied, but the authenticated user is not</div> <div class="line">authorized to directly access the object protected by Access</div> <div class="line">Permissions and/or Access Restrictions (“Terms of Use”).</div> </div> </div> </div> </div> <div class="section" id="data-deposit-api"> <span id="id2"></span><h2>Data Deposit API<a class="headerlink" href="#data-deposit-api" title="Permalink to this headline">¶</a></h2> <p>As of version 3.6, a new API for programmatic deposit of data and metadata to the Dataverse Network has been added. The API allows a remote, non-Dataverse Network archive/application to deposit files and metadata to a Dataverse Network installation.</p> <div class="section" id="overview-of-data-deposit-api"> <h3>Overview of Data Deposit API<a class="headerlink" href="#overview-of-data-deposit-api" title="Permalink to this headline">¶</a></h3> <p>“v1” of the DVN Data Deposit API is a partial implementation of the SWORDv2 protocol, the specification for which available at <a class="reference external" href="http://swordapp.github.io/SWORDv2-Profile/SWORDProfile.html">http://swordapp.github.io/SWORDv2-Profile/SWORDProfile.html</a></p> <p>Please reference the SWORDv2 specification for expected HTTP status codes (i.e. 201, 204, 404, etc.), headers (i.e. “Location”), etc.</p> <div class="section" id="data-deposit-api-v1-curl-examples"> <h4>Data Deposit API v1 <cite>curl</cite> examples<a class="headerlink" href="#data-deposit-api-v1-curl-examples" title="Permalink to this headline">¶</a></h4> <p>The following <cite>curl</cite> commands demonstrate supported operations:</p> <div class="section" id="retrieve-sword-service-document"> <h5>Retrieve SWORD service document<a class="headerlink" href="#retrieve-sword-service-document" title="Permalink to this headline">¶</a></h5> <p>The service document enumerates the dataverses (“collections” from a SWORD perspective) the user can deposit data into. The “collectionPolicy” element for each dataverse contains the deposit terms of use for the network and dataverse.</p> <p><tt class="docutils literal"><span class="pre">curl</span> <span class="pre">https://$USERNAME:$PASSWORD@$DVN_SERVER/dvn/api/data-deposit/v1/swordv2/service-document</span></tt></p> </div> <div class="section" id="create-a-study-with-an-atom-entry-xml-file"> <h5>Create a study with an Atom entry (XML file)<a class="headerlink" href="#create-a-study-with-an-atom-entry-xml-file" title="Permalink to this headline">¶</a></h5> <p><tt class="docutils literal"><span class="pre">curl</span> <span class="pre">--data-binary</span> <span class="pre">"@atom-entry-study.xml"</span> <span class="pre">-H</span> <span class="pre">"Content-Type:</span> <span class="pre">application/atom+xml"</span> <span class="pre">https://$USERNAME:$PASSWORD@$DVN_SERVER/dvn/api/data-deposit/v1/swordv2/collection/dataverse/$DATAVERSE_ALIAS</span></tt></p> <div class="highlight-guess"><div class="highlight"><pre><span class="cp"><?xml version="1.0"?></span> <span class="c"><!--</span> <span class="c">modified from http://swordapp.github.io/SWORDv2-Profile/SWORDProfile.html#protocoloperations_editingcontent_metadata</span> <span class="c">--></span> <span class="nt"><entry</span> <span class="na">xmlns=</span><span class="s">"http://www.w3.org/2005/Atom"</span> <span class="na">xmlns:dcterms=</span><span class="s">"http://purl.org/dc/terms/"</span><span class="nt">></span> <span class="c"><!-- some embedded metadata --></span> <span class="nt"><dcterms:title></span>Roasting at Home<span class="nt"></dcterms:title></span> <span class="nt"><dcterms:creator></span>Peets, John<span class="nt"></dcterms:creator></span> <span class="nt"><dcterms:creator></span>Stumptown, Jane<span class="nt"></dcterms:creator></span> <span class="c"><!-- Producer with financial or admin responsibility of the data --></span> <span class="nt"><dcterms:publisher></span>Coffee Bean State University<span class="nt"></dcterms:publisher></span> <span class="c"><!-- related publications --></span> <span class="nt"><dcterms:isReferencedBy</span> <span class="na">holdingsURI=</span><span class="s">"http://dx.doi.org/10.1038/dvn333"</span> <span class="na">agency=</span><span class="s">"DOI"</span> <span class="na">IDNo=</span><span class="s">"10.1038/dvn333"</span><span class="nt">></span>Peets, J., <span class="ni">&amp;</span> Stumptown, J. (2013). Roasting at Home. New England Journal of Coffee, 3(1), 22-34.<span class="nt"></dcterms:isReferencedBy></span> <span class="c"><!-- production date --></span> <span class="nt"><dcterms:date></span>2013-07-11<span class="nt"></dcterms:date></span> <span class="c"><!-- Other Identifier for the data in this study (or potentially global id if unused) --></span> <span class="c"><!--</span> <span class="c"> <dcterms:identifier>hdl:1XXZY.1/XYXZ</dcterms:identifier></span> <span class="c"> --></span> <span class="nt"><dcterms:description></span>Considerations before you start roasting your own coffee at home.<span class="nt"></dcterms:description></span> <span class="c"><!-- keywords --></span> <span class="nt"><dcterms:subject></span>coffee<span class="nt"></dcterms:subject></span> <span class="nt"><dcterms:subject></span>beverage<span class="nt"></dcterms:subject></span> <span class="nt"><dcterms:subject></span>caffeine<span class="nt"></dcterms:subject></span> <span class="c"><!-- geographic coverage --></span> <span class="nt"><dcterms:coverage></span>United States<span class="nt"></dcterms:coverage></span> <span class="nt"><dcterms:coverage></span>Canada<span class="nt"></dcterms:coverage></span> <span class="c"><!-- kind of data --></span> <span class="nt"><dcterms:type></span>aggregate data<span class="nt"></dcterms:type></span> <span class="c"><!-- List of sources of the data collection--></span> <span class="nt"><dcterms:source></span>Stumptown, Jane. 2011. Home Roasting. Coffeemill Press.<span class="nt"></dcterms:source></span> <span class="c"><!-- restrictions --></span> <span class="nt"><dcterms:rights></span>Creative Commons CC-BY 3.0 (unported) http://creativecommons.org/licenses/by/3.0/<span class="nt"></dcterms:rights></span> <span class="c"><!-- related materials --></span> <span class="nt"><dcterms:relation></span>Peets, John. 2010. Roasting Coffee at the Coffee Shop. Coffeemill Press<span class="nt"></dcterms:relation></span> <span class="nt"></entry></span> </pre></div> </div> </div> <div class="section" id="dublin-core-dc-qualified-mapping-ddi-dataverse-network-db-element-crosswalk"> <h5>Dublin Core (DC) Qualified Mapping - DDI - Dataverse Network DB Element Crosswalk<a class="headerlink" href="#dublin-core-dc-qualified-mapping-ddi-dataverse-network-db-element-crosswalk" title="Permalink to this headline">¶</a></h5> <table border="1" class="docutils"> <colgroup> <col width="12%" /> <col width="19%" /> <col width="13%" /> <col width="57%" /> </colgroup> <thead valign="bottom"> <tr class="row-odd"><th class="head">DC (terms: namespace)</th> <th class="head">DVN DB Element</th> <th class="head">DDI Element 2.x</th> <th class="head">Note</th> </tr> </thead> <tbody valign="top"> <tr class="row-even"><td>dcterms:title</td> <td>title</td> <td>2.1.1.1 title</td> <td> </td> </tr> <tr class="row-odd"><td>dcterms:creator</td> <td>author (LastName, FirstName)</td> <td>2.1.2.1 AuthEnty</td> <td> </td> </tr> <tr class="row-even"><td>dcterms:subject</td> <td>keyword</td> <td>2.2.1.1. keyword</td> <td> </td> </tr> <tr class="row-odd"><td>dcterms:description</td> <td>abstract</td> <td>2.2.2 abstract</td> <td>Describing the purpose, scope or nature of the data collection...</td> </tr> <tr class="row-even"><td>dcterms:publisher</td> <td>producer</td> <td>2.1.3.1 producer</td> <td>person or agency financially or administratively responsible for the dataset</td> </tr> <tr class="row-odd"><td>dcterms:contributor</td> <td>n/a</td> <td>n/a</td> <td>see dcterms:creator above</td> </tr> <tr class="row-even"><td>dcterms:date</td> <td>productionDate (YYYY-MM-DD or YYYY-MM or YYYY)</td> <td>2.1.3.3 prodDate</td> <td>production or published date of dataset</td> </tr> <tr class="row-odd"><td>dcterms:type</td> <td>kindOfData</td> <td>2.2.3.10 dataKind</td> <td>Type of data included in the file: survey data, census/enumeration data, aggregate data, clinical</td> </tr> <tr class="row-even"><td>dcterms:format</td> <td>n/a</td> <td>n/a</td> <td> </td> </tr> <tr class="row-odd"><td>dcterms:identifier</td> <td>otherID</td> <td>2.1.1.5 IDNo</td> <td>Don’t use this field to map a journal article ID. Only ID’s that directly belong to dataset</td> </tr> <tr class="row-even"><td>dcterms:source</td> <td>dataSources</td> <td>2.3.1.8.1 dataSrc</td> <td>List of books, articles, data files if any that served as the sources for the data collection</td> </tr> <tr class="row-odd"><td>dcterms:language</td> <td>n/a</td> <td>n/a</td> <td> </td> </tr> <tr class="row-even"><td>dcterms:relation</td> <td>relatedMaterial</td> <td>2.5.1 relMat</td> <td>any related material (journal article is not included here - see: dcterms:isReferencedBy below)</td> </tr> <tr class="row-odd"><td>dcterms:coverage</td> <td>geographicCoverage</td> <td>2.2.3.4 geogCover</td> <td>Info on the geographic coverage of the data</td> </tr> <tr class="row-even"><td>dcterms:rights</td> <td>restrictions</td> <td>2.4.2.3 restrctn</td> <td>any restrictions on the access or use of the dataset</td> </tr> <tr class="row-odd"><td>dcterms:bibliographicCitation</td> <td>dataCitation</td> <td>? (2.1.7 biblCit)</td> <td>data citation for the study in the Dataverse Network</td> </tr> <tr class="row-even"><td>dcterms:isReferencedBy</td> <td>studyRelPublications</td> <td>? (not set by DDI community yet)</td> <td>the publication (journal article, book, other work) that uses this dataset (include citation, permanent identifier (DOI), and permanent URL)</td> </tr> </tbody> </table> </div> <div class="section" id="add-files-to-a-study-with-a-zip-file"> <h5>Add files to a study with a zip file<a class="headerlink" href="#add-files-to-a-study-with-a-zip-file" title="Permalink to this headline">¶</a></h5> <p><tt class="docutils literal"><span class="pre">curl</span> <span class="pre">--data-binary</span> <span class="pre">@example.zip</span> <span class="pre">-H</span> <span class="pre">"Content-Disposition:</span> <span class="pre">filename=example.zip"</span> <span class="pre">-H</span> <span class="pre">"Content-Type:</span> <span class="pre">application/zip"</span> <span class="pre">-H</span> <span class="pre">"Packaging:</span> <span class="pre">http://purl.org/net/sword/package/SimpleZip"</span> <span class="pre">https://$USERNAME:$PASSWORD@$DVN_SERVER/dvn/api/data-deposit/v1/swordv2/edit-media/study/hdl:TEST/12345</span></tt></p> </div> <div class="section" id="display-a-study-atom-entry"> <h5>Display a study atom entry<a class="headerlink" href="#display-a-study-atom-entry" title="Permalink to this headline">¶</a></h5> <p>Contains data citation (bibliographicCitation), alternate URI [persistent URI of study], edit URI, edit media URI, statement URI.</p> <p><tt class="docutils literal"><span class="pre">curl</span> <span class="pre">https://$USERNAME:$PASSWORD@$DVN_SERVER/dvn/api/data-deposit/v1/swordv2/edit/study/hdl:TEST/12345</span></tt></p> </div> <div class="section" id="display-a-study-statement"> <h5>Display a study statement<a class="headerlink" href="#display-a-study-statement" title="Permalink to this headline">¶</a></h5> <p>Contains feed of file entries, latestVersionState, locked boolean</p> <p><tt class="docutils literal"><span class="pre">curl</span> <span class="pre">https://$USERNAME:$PASSWORD@$DVN_SERVER/dvn/api/data-deposit/v1/swordv2/statement/study/hdl:TEST/12345</span></tt></p> </div> <div class="section" id="delete-a-file-by-database-id"> <h5>Delete a file by database id<a class="headerlink" href="#delete-a-file-by-database-id" title="Permalink to this headline">¶</a></h5> <p><tt class="docutils literal"><span class="pre">curl</span> <span class="pre">-i</span> <span class="pre">-X</span> <span class="pre">DELETE</span> <span class="pre">https://$USERNAME:$PASSWORD@$DVN_SERVER/dvn/api/data-deposit/v1/swordv2/edit-media/file/2325541</span></tt></p> </div> <div class="section" id="replacing-cataloging-information-title-author-etc-for-a-study"> <h5>Replacing cataloging information (title, author, etc.) for a study<a class="headerlink" href="#replacing-cataloging-information-title-author-etc-for-a-study" title="Permalink to this headline">¶</a></h5> <p>Please note that all cataloging information will be replaced, including fields that can not be expressed with “dcterms” fields.</p> <p><tt class="docutils literal"><span class="pre">curl</span> <span class="pre">--upload-file</span> <span class="pre">"atom-entry-study2.xml"</span> <span class="pre">-H</span> <span class="pre">"Content-Type:</span> <span class="pre">application/atom+xml"</span> <span class="pre">https://$USERNAME:$PASSWORD@$DVN_SERVER/dvn/api/data-deposit/v1/swordv2/edit/study/hdl:TEST/12345</span></tt></p> <div class="highlight-guess"><div class="highlight"><pre><span class="cp"><?xml version="1.0"?></span> <span class="c"><!--</span> <span class="c">for modifying a study created with atom-entry-study.xml</span> <span class="c">--></span> <span class="nt"><entry</span> <span class="na">xmlns=</span><span class="s">"http://www.w3.org/2005/Atom"</span> <span class="na">xmlns:dcterms=</span><span class="s">"http://purl.org/dc/terms/"</span><span class="nt">></span> <span class="c"><!-- some embedded metadata --></span> <span class="nt"><dcterms:title></span>The Levels of Caffeine in Cold Brew Coffee<span class="nt"></dcterms:title></span> <span class="nt"><dcterms:creator></span>Peets, John L.<span class="nt"></dcterms:creator></span> <span class="nt"><dcterms:creator></span>Stumptown Research Institute<span class="nt"></dcterms:creator></span> <span class="nt"><dcterms:isReferencedBy</span> <span class="na">holdingsURI=</span><span class="s">"http://dx.doi.org/10.1038/dvn333"</span> <span class="na">agency=</span><span class="s">"DOI"</span> <span class="na">IDNo=</span><span class="s">"10.1038/dvn333"</span><span class="nt">></span>Peets, J., <span class="ni">&amp;</span> Stumptown, J. (2013). Roasting at Home. New England Journal of Coffee, 3(1), 22-34.<span class="nt"></dcterms:isReferencedBy></span> <span class="nt"><dcterms:date></span>2013-08-11<span class="nt"></dcterms:date></span> <span class="nt"><dcterms:description></span>This study evaluates the caffeine levels of a cold brewed coffee.<span class="nt"></dcterms:description></span> <span class="nt"><dcterms:subject></span>coffee bean<span class="nt"></dcterms:subject></span> <span class="nt"><dcterms:subject></span>caffeine<span class="nt"></dcterms:subject></span> <span class="nt"><dcterms:subject></span>cold brew process<span class="nt"></dcterms:subject></span> <span class="nt"><dcterms:subject></span>Stumptown Coffee Company<span class="nt"></dcterms:subject></span> <span class="nt"><dcterms:rights></span>Creative Commons CC-BY 3.0 (unported) http://creativecommons.org/licenses/by/3.0/<span class="nt"></dcterms:rights></span> <span class="nt"></entry></span> </pre></div> </div> </div> <div class="section" id="list-studies-in-a-dataverse"> <h5>List studies in a dataverse<a class="headerlink" href="#list-studies-in-a-dataverse" title="Permalink to this headline">¶</a></h5> <p><tt class="docutils literal"><span class="pre">curl</span> <span class="pre">https://$USERNAME:$PASSWORD@$DVN_SERVER/dvn/api/data-deposit/v1/swordv2/collection/dataverse/$DATAVERSE_ALIAS</span></tt></p> </div> <div class="section" id="delete-a-study-non-released-studies-only"> <h5>Delete a study (non-released studies only)<a class="headerlink" href="#delete-a-study-non-released-studies-only" title="Permalink to this headline">¶</a></h5> <p><tt class="docutils literal"><span class="pre">curl</span> <span class="pre">-i</span> <span class="pre">-X</span> <span class="pre">DELETE</span> <span class="pre">https://$USERNAME:$PASSWORD@$DVN_SERVER/dvn/api/data-deposit/v1/swordv2/edit/study/hdl:TEST/12345</span></tt></p> </div> <div class="section" id="deaccession-a-study-released-studies-only"> <h5>Deaccession a study (released studies only)<a class="headerlink" href="#deaccession-a-study-released-studies-only" title="Permalink to this headline">¶</a></h5> <p><tt class="docutils literal"><span class="pre">curl</span> <span class="pre">-i</span> <span class="pre">-X</span> <span class="pre">DELETE</span> <span class="pre">https://$USERNAME:$PASSWORD@$DVN_SERVER/dvn/api/data-deposit/v1/swordv2/edit/study/hdl:TEST/12345</span></tt></p> </div> <div class="section" id="release-a-study"> <h5>Release a study<a class="headerlink" href="#release-a-study" title="Permalink to this headline">¶</a></h5> <p><tt class="docutils literal"><span class="pre">curl</span> <span class="pre">-X</span> <span class="pre">POST</span> <span class="pre">-H</span> <span class="pre">"In-Progress:</span> <span class="pre">false"</span> <span class="pre">--upload-file</span> <span class="pre">zero-length-file.txt</span> <span class="pre">https://$USERNAME:$PASSWORD@$DVN_SERVER/dvn/api/data-deposit/v1/swordv2/edit/study/hdl:TEST/12345</span></tt></p> </div> <div class="section" id="determine-if-a-dataverse-has-been-released"> <h5>Determine if a dataverse has been released<a class="headerlink" href="#determine-if-a-dataverse-has-been-released" title="Permalink to this headline">¶</a></h5> <p>Look for a <cite>dataverseHasBeenReleased</cite> boolean.</p> <p><tt class="docutils literal"><span class="pre">curl</span> <span class="pre">https://$USERNAME:$PASSWORD@$DVN_SERVER/dvn/api/data-deposit/v1/swordv2/collection/dataverse/$DATAVERSE_ALIAS</span></tt></p> </div> </div> <div class="section" id="curl-reference"> <h4><cite>curl</cite> reference<a class="headerlink" href="#curl-reference" title="Permalink to this headline">¶</a></h4> <p>Per <a class="reference external" href="http://curl.haxx.se/docs/manpage.html">http://curl.haxx.se/docs/manpage.html</a></p> <ul class="simple"> <li><cite>–upload-file</cite> is an HTTP <cite>PUT</cite></li> <li><cite>–data-binary</cite> is an HTTP <cite>POST</cite></li> </ul> </div> </div> <div class="section" id="dvn-data-deposit-api-v1-client-sample-code-python"> <h3>DVN Data Deposit API v1 client sample code (Python)<a class="headerlink" href="#dvn-data-deposit-api-v1-client-sample-code-python" title="Permalink to this headline">¶</a></h3> <p><a class="reference external" href="https://github.com/dvn/swordpoc/tree/master/dvn_client">https://github.com/dvn/swordpoc/tree/master/dvn_client</a> contains sample Python code for writing a DVN Data Deposit API v1 client. It makes use of a Python client library which conforms to the SWORDv2 specification: <a class="reference external" href="https://github.com/swordapp/python-client-sword2">https://github.com/swordapp/python-client-sword2</a></p> </div> <div class="section" id="swordv2-client-libraries"> <h3>SWORDv2 client libraries<a class="headerlink" href="#swordv2-client-libraries" title="Permalink to this headline">¶</a></h3> <ul class="simple"> <li>Python: <a class="reference external" href="https://github.com/swordapp/python-client-sword2">https://github.com/swordapp/python-client-sword2</a></li> <li>Java: <a class="reference external" href="https://github.com/swordapp/JavaClient2.0">https://github.com/swordapp/JavaClient2.0</a></li> <li>Ruby: <a class="reference external" href="https://github.com/swordapp/sword2ruby">https://github.com/swordapp/sword2ruby</a></li> <li>PHP: <a class="reference external" href="https://github.com/swordapp/swordappv2-php-library">https://github.com/swordapp/swordappv2-php-library</a></li> </ul> </div> </div> </div> </div> </div> </div> </div> <div class="sidebar"> <h3>Table Of Contents</h3> <ul class="current"> <li class="toctree-l1"><a class="reference internal" href="dataverse-user-main.html">User Guide</a></li> <li class="toctree-l1"><a class="reference internal" href="dataverse-installer-main.html">Installers Guide</a></li> <li class="toctree-l1"><a class="reference internal" href="dataverse-developer-main.html">DVN Developers Guide</a></li> <li class="toctree-l1 current"><a class="current reference internal" href="">APIs Guide</a><ul> <li class="toctree-l2"><a class="reference internal" href="#data-sharing-api">Data Sharing API</a><ul> <li class="toctree-l3"><a class="reference internal" href="#api-urls">API URLs</a></li> <li class="toctree-l3"><a class="reference internal" href="#metadata-api">Metadata API</a><ul> <li class="toctree-l4"><a class="reference internal" href="#metadatasearchfields">metadataSearchFields</a></li> <li class="toctree-l4"><a class="reference internal" href="#metadatasearch">metadataSearch</a></li> <li class="toctree-l4"><a class="reference internal" href="#metadataformatsavailable">metadataFormatsAvailable</a></li> <li class="toctree-l4"><a class="reference internal" href="#metadata">metadata</a></li> </ul> </li> <li class="toctree-l3"><a class="reference internal" href="#file-access-api">File Access API</a><ul> <li class="toctree-l4"><a class="reference internal" href="#downloadinfo">downloadInfo</a></li> <li class="toctree-l4"><a class="reference internal" href="#download">download</a></li> </ul> </li> </ul> </li> <li class="toctree-l2"><a class="reference internal" href="#data-deposit-api">Data Deposit API</a><ul> <li class="toctree-l3"><a class="reference internal" href="#overview-of-data-deposit-api">Overview of Data Deposit API</a><ul> <li class="toctree-l4"><a class="reference internal" href="#data-deposit-api-v1-curl-examples">Data Deposit API v1 <cite>curl</cite> examples</a><ul> <li class="toctree-l5"><a class="reference internal" href="#retrieve-sword-service-document">Retrieve SWORD service document</a></li> <li class="toctree-l5"><a class="reference internal" href="#create-a-study-with-an-atom-entry-xml-file">Create a study with an Atom entry (XML file)</a></li> <li class="toctree-l5"><a class="reference internal" href="#dublin-core-dc-qualified-mapping-ddi-dataverse-network-db-element-crosswalk">Dublin Core (DC) Qualified Mapping - DDI - Dataverse Network DB Element Crosswalk</a></li> <li class="toctree-l5"><a class="reference internal" href="#add-files-to-a-study-with-a-zip-file">Add files to a study with a zip file</a></li> <li class="toctree-l5"><a class="reference internal" href="#display-a-study-atom-entry">Display a study atom entry</a></li> <li class="toctree-l5"><a class="reference internal" href="#display-a-study-statement">Display a study statement</a></li> <li class="toctree-l5"><a class="reference internal" href="#delete-a-file-by-database-id">Delete a file by database id</a></li> <li class="toctree-l5"><a class="reference internal" href="#replacing-cataloging-information-title-author-etc-for-a-study">Replacing cataloging information (title, author, etc.) for a study</a></li> <li class="toctree-l5"><a class="reference internal" href="#list-studies-in-a-dataverse">List studies in a dataverse</a></li> <li class="toctree-l5"><a class="reference internal" href="#delete-a-study-non-released-studies-only">Delete a study (non-released studies only)</a></li> <li class="toctree-l5"><a class="reference internal" href="#deaccession-a-study-released-studies-only">Deaccession a study (released studies only)</a></li> <li class="toctree-l5"><a class="reference internal" href="#release-a-study">Release a study</a></li> <li class="toctree-l5"><a class="reference internal" href="#determine-if-a-dataverse-has-been-released">Determine if a dataverse has been released</a></li> </ul> </li> <li class="toctree-l4"><a class="reference internal" href="#curl-reference"><cite>curl</cite> reference</a></li> </ul> </li> <li class="toctree-l3"><a class="reference internal" href="#dvn-data-deposit-api-v1-client-sample-code-python">DVN Data Deposit API v1 client sample code (Python)</a></li> <li class="toctree-l3"><a class="reference internal" href="#swordv2-client-libraries">SWORDv2 client libraries</a></li> </ul> </li> </ul> </li> </ul> <h3 style="margin-top: 1.5em;">Search</h3> <form class="search" action="search.html" method="get"> <input type="text" name="q" /> <input type="submit" value="Go" /> <input type="hidden" name="check_keywords" value="yes" /> <input type="hidden" name="area" value="default" /> </form> <p class="searchtip" style="font-size: 90%"> Enter search terms. </p> </div> <div class="clearer"></div> </div> </div> <div class="footer-wrapper"> <div class="footer"> <div class="left"> <a href="dataverse-developer-main.html" title="DVN Developers Guide" >previous</a> | <a href="genindex.html" title="General Index" >index</a> <br/> <a href="_sources/dataverse-api-main.txt" rel="nofollow">Show Source</a> </div> <div class="right"> <div class="footer"> © Copyright 1997-2013, President & Fellows Harvard University. Created using <a href="http://sphinx-doc.org/">Sphinx</a> 1.2b1. </div> </div> <div class="clearer"></div> </div> </div> </body> </html>