<!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>REST Interface Overview — v2.1.0-beta</title> <link rel="stylesheet" href="../_static/dataone.css" type="text/css" /> <link rel="stylesheet" href="../_static/pygments.css" type="text/css" /> <script type="text/javascript"> var DOCUMENTATION_OPTIONS = { URL_ROOT: '../', VERSION: '2.1.0-beta', COLLAPSE_INDEX: false, FILE_SUFFIX: '.html', HAS_SOURCE: true, SOURCELINK_SUFFIX: '.txt' }; </script> <script type="text/javascript" src="../_static/mathjax_pre.js"></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="//cdn.mathjax.org/mathjax/latest/MathJax.js?config=TeX-MML-AM_CHTML"></script> <script type="text/javascript" src="../_static/sidebar.js"></script> <link rel="author" title="About these documents" href="../about.html" /> <link rel="index" title="Index" href="../genindex.html" /> <link rel="search" title="Search" href="../search.html" /> <link rel="next" title="Member Node APIs" href="MN_APIs.html" /> <link rel="prev" title="DataONE APIs" href="index.html" /> <link media="only screen and (max-device-width: 480px)" href="../_static/small_dataone.css" type= "text/css" rel="stylesheet" /> </head> <body role="document"> <div class="version_notice"> <p> <span class='bold'>Warning:</span> These documents are under active development and subject to change (version 2.1.0-beta).<br /> The latest release documents are at: <a href="https://purl.dataone.org/architecture">https://purl.dataone.org/architecture</a> </p> </div> <div class="related" role="navigation" aria-label="related navigation"> <h3>Navigation</h3> <ul> <li class="right" style="margin-right: 10px"> <a href="../genindex.html" title="General Index" accesskey="I">index</a></li> <li class="right" > <a href="../py-modindex.html" title="Python Module Index" >modules</a> |</li> <li class="right" > <a href="MN_APIs.html" title="Member Node APIs" accesskey="N">next</a> |</li> <li class="right" > <a href="index.html" title="DataONE APIs" accesskey="P">previous</a> |</li> <li class="nav-item nav-item-0"><a href="../index.html"></a> »</li> <li class="nav-item nav-item-1"><a href="index.html" accesskey="U">DataONE APIs</a> »</li> </ul> </div> <div class="document"> <div class="documentwrapper"> <div class="bodywrapper"> <div class="body"> <div class="section" id="rest-interface-overview"> <h1>REST Interface Overview<a class="headerlink" href="#rest-interface-overview" title="Permalink to this headline">¶</a></h1> <p>This document describes how the Member (<a class="reference internal" href="MN_APIs.html"><span class="doc">Member Node APIs</span></a>) and Coordinating (<a class="reference internal" href="CN_APIs.html"><span class="doc">Coordinating Node APIs</span></a>) Node APIs are implemented using a Representational State Transfer (REST) approach over HTTP.</p> <p>Key points on REST interactions in DataONE:</p> <ol class="arabic simple"> <li>Content is generally modeled as collections, with <a class="reference internal" href="Types.html#Types.Identifier" title="Types.Identifier"><code class="xref py py-class docutils literal"><span class="pre">PIDs</span></code></a> identifying individual items of a collection.</li> <li>The HTTP verbs HEAD, GET, POST, PUT, DELETE are used for retrieving information about content, retrieving content, creating content, updating content, and deleting content respectively.</li> <li>State information, if required, is passed in the HTTP headers.</li> <li>Identity transfer is performed using SSL, with the client certificate accessible through implementation specific mechanisms supported by the respective server environment.</li> <li>The identity information described in (4) is indicated as a <em>Session</em> in the method signatures and their descriptions.</li> <li>Hints to support efficient caching (e.g. content time stamps) should be respected. Caching is an important mechanism for assisting with service scalability.</li> <li>Names of parameters passed in URLs or message bodies are case sensitive unless explicitly indicated otherwise. If the case of the parameters names does not match the method signature, the request MAY be rejected with an <a class="reference internal" href="Exceptions.html#Exceptions.InvalidRequest" title="Exceptions.InvalidRequest"><code class="xref py py-exc docutils literal"><span class="pre">Exceptions.InvalidRequest</span></code></a> exception.</li> <li>GET, HEAD, DELETE requests only pass parameters as part of the URL. The parameter values are converted to UTF-8 Strings and appropriately escaped for incorporating into the URL.</li> <li>Message bodies (e.g. for POST and PUT requests) are encoded using MIME Multipart, mixed (<a class="reference external" href="http://tools.ietf.org/html/rfc2046#section-5.1.3">RFC2046</a>).</li> <li>PUT requests are for updating an existing resource. An identifier of some sort will typically appear in the URL (e.g. a PID or a Subject), which should be a UTF-8 string and appropriately URL path encoded. The message body will be MIME multipart/mixed and may contain values expressed as parameter and / or file parts as described in (12) below.</li> <li>POST requests are for creating resources. All information for creating the new object or resource is transmitted in the message body, which is encoded as a MIME multipart/mixed message.</li> <li>We use two types of content in MIME multipart/mixed messages: parameters and files. Parameters are to be used for all simple types (13, below). Files are to be used for all complex types (14, below) and for octet streams.</li> <li>Simple types are structures that contain a single value. When creating the parameter entry, the value is converted to a UTF-8 String using formatting equivalent to what is used when expressing the same value as part of an XML document (e.g. when serializing using PyxB or JibX). The expression of a simple type as a String in a MIME multipart/mixed parameter should be equivalent to expressing the same value as part of a URL (before escaping).</li> <li>Complex types are any structures that contain more than a single value. A simple example of a complex type is the <a class="reference internal" href="Types.html#Types.Checksum" title="Types.Checksum"><code class="xref py py-class docutils literal"><span class="pre">Types.Checksum</span></code></a> type. It is a String (the checksum) with an attribute (the algorithm). Complex types are serialized to UTF-8 encoded XML structures that are defined by the DataONE Types Schema.</li> <li>File parts of MIME multipart/mixed have three properties: the name of the entry, the file name of the content, and the content. The name of the entry must match the parameter name as described in the signature of the method being called. The content of the entry is XML encoded structure as described in (14) above (or an octet stream). The file name property is not used, and can be set to whatever the client considers appropriate. The file name MAY be ignored by the service receiving the request.</li> </ol> <p>Collections exposed by <a class="reference internal" href="../glossary.html#term-member-node"><span class="xref std std-term">Member Node</span></a>s and <a class="reference internal" href="../glossary.html#term-coordinating-node"><span class="xref std std-term">Coordinating Node</span></a>s include:</p> <table class="docutils field-list" frame="void" rules="none"> <col class="field-name" /> <col class="field-body" /> <tbody valign="top"> <tr class="field-odd field"><th class="field-name"><code class="docutils literal"><span class="pre">/object</span></code>:</th><td class="field-body">The set of objects available for retrieval from the node.</td> </tr> <tr class="field-even field"><th class="field-name"><code class="docutils literal"><span class="pre">/meta</span></code>:</th><td class="field-body">Metadata about objects available for retrieval from the node.</td> </tr> <tr class="field-odd field"><th class="field-name"><code class="docutils literal"><span class="pre">/formats</span></code>:</th><td class="field-body">Object formats registered on the node.</td> </tr> <tr class="field-even field"><th class="field-name"><code class="docutils literal"><span class="pre">/log</span></code>:</th><td class="field-body">Log records held on the node.</td> </tr> <tr class="field-odd field"><th class="field-name"><code class="docutils literal"><span class="pre">/reserve</span></code>:</th><td class="field-body">Identifiers that have been reserved for future use.</td> </tr> <tr class="field-even field"><th class="field-name"><code class="docutils literal"><span class="pre">/accounts</span></code>:</th><td class="field-body">Principal and ownership related functionality.</td> </tr> <tr class="field-odd field"><th class="field-name"><code class="docutils literal"><span class="pre">/sessions</span></code>:</th><td class="field-body">Authenticated session management functions.</td> </tr> <tr class="field-even field"><th class="field-name"><code class="docutils literal"><span class="pre">/node</span></code>:</th><td class="field-body">Service and status information for all nodes on the system.</td> </tr> <tr class="field-odd field"><th class="field-name"><code class="docutils literal"><span class="pre">/monitor</span></code>:</th><td class="field-body">Node health monitoring</td> </tr> <tr class="field-even field"><th class="field-name"><code class="docutils literal"><span class="pre">/replicate</span></code>:</th><td class="field-body">Member node to member node replication functionality</td> </tr> </tbody> </table> <div class="section" id="message-serialization"> <h2>Message Serialization<a class="headerlink" href="#message-serialization" title="Permalink to this headline">¶</a></h2> <p>The format of the response (except for responses from <a class="reference internal" href="MN_APIs.html#MNRead.get" title="MNRead.get"><code class="xref py py-func docutils literal"><span class="pre">MNRead.get()</span></code></a> or <a class="reference internal" href="CN_APIs.html#CNRead.get" title="CNRead.get"><code class="xref py py-func docutils literal"><span class="pre">CNRead.get()</span></code></a>) is determined by the <em>Accept:</em> header provided in the request.</p> <p>Version 1.0 of the DataONE services only support XML serialization, and this format MUST be supported by all services and clients interacting with the DataONE system.</p> <p>All request and response documents MUST be encoded using the UTF-8 character set.</p> <p>If the service is not able to provide a response in the specified format, then the node should return an error code of <a class="reference internal" href="Exceptions.html#Exceptions.NotImplemented" title="Exceptions.NotImplemented"><code class="xref py py-exc docutils literal"><span class="pre">Exceptions.NotImplemented</span></code></a>, with the HTTP error code set to 406.</p> </div> <div class="section" id="parameters-in-requests"> <h2>Parameters in Requests<a class="headerlink" href="#parameters-in-requests" title="Permalink to this headline">¶</a></h2> <p>Many of the URL patterns described here accept parameters in the URL and as components of a MIME multipart-mixed message body.</p> <p>Unless otherwise indicated, all parameter names and values should be considered case sensitive.</p> <div class="admonition note"> <p class="first admonition-title">Note</p> <p class="last">The default configuration of web servers such as Apache introduces some ambiguity in the interpretation of URLs that include slashes and other reserved characters that are used as path separators for example. The document <a class="reference internal" href="../notes/ApacheConfiguration.html"><span class="doc">Apache Configuration for DataONE Services</span></a> describes appropriate configuration details for the Apache web server.</p> </div> <div class="section" id="session-information"> <h3>Session Information<a class="headerlink" href="#session-information" title="Permalink to this headline">¶</a></h3> <p>Session information (formerly referred to as a <em>token</em>) is obtained from the client side authentication certificate held by the SSL processing library of the HTTPS service handling the request. Hence, even though a <em>session</em> parameter may be present in the method signature, the session information itself is transported as part of the HTTPS handshaking process and is not present in the body or header section of the HTTP request.</p> </div> <div class="section" id="url-path-parameters"> <h3>URL Path Parameters<a class="headerlink" href="#url-path-parameters" title="Permalink to this headline">¶</a></h3> <p>Some parameters are passed as part of the REST service URL path (e.g. /get/{pid}). Such values MUST be encoded according to the rules of <a class="reference external" href="http://tools.ietf.org/html/rfc3986">RFC3986</a> with the additional restriction that the space character MUST be encoded as “%20” rather than “+”. Examples of DataONE REST URLs for retrieving an object (i.e. the get() operation):</p> <div class="highlight-default"><div class="highlight"><pre><span></span>PID: 10.1000/182 URL: https://mn.example.com/mn/v1/object/10.1000%2F182 PID: http://example.com/data/mydata?row=24 URL: https://mn.example.com/mn/v1/object/http:%2F%2Fexample.com%2Fdata%2Fmydata%3Frow=24 PID: Is_féidir_liom_ithe_gloine URL: https://mn.example.com/mn/v1/object/Is_f%C3%A9idir_liom_ithe_gloine </pre></div> </div> </div> <div class="section" id="url-query-parameters"> <h3>URL Query Parameters<a class="headerlink" href="#url-query-parameters" title="Permalink to this headline">¶</a></h3> <p>Parameters passed as key, values parameters in the URL query string MUST be appropriately encoded for transmission as part of the URL according to <a class="reference external" href="http://tools.ietf.org/html/rfc3986">RFC3986</a> rules for the URL query component. In addition, the space character MUST be encoded as “%20” rather than the alternative “+” character.</p> </div> <div class="section" id="boolean-url-query-parameters"> <h3>Boolean URL Query Parameters<a class="headerlink" href="#boolean-url-query-parameters" title="Permalink to this headline">¶</a></h3> <p>Where a boolean parameter value is being specified as the value portion of a key-value pair appearing in a URL, the strings “true” and “false” MUST be used to indicate logical true and logical false respectively.</p> </div> <div class="section" id="date-parameters-in-urls"> <h3>Date Parameters in URLs<a class="headerlink" href="#date-parameters-in-urls" title="Permalink to this headline">¶</a></h3> <p>Date values in URLs should be formatted as:</p> <div class="highlight-default"><div class="highlight"><pre><span></span><span class="n">yyyy</span><span class="o">-</span><span class="n">MM</span><span class="o">-</span><span class="n">dd</span><span class="p">[</span><span class="n">Thh</span><span class="p">:</span><span class="n">mm</span><span class="p">:</span><span class="n">ss</span><span class="o">.</span><span class="n">S</span><span class="p">[</span><span class="o">+</span><span class="n">ZZ</span><span class="p">:</span><span class="n">zz</span><span class="p">]]</span> </pre></div> </div> <p>Where:</p> <div class="highlight-default"><div class="highlight"><pre><span></span><span class="n">yyyy</span> <span class="o">=</span> <span class="n">Four</span> <span class="n">digit</span> <span class="n">year</span> <span class="n">MM</span> <span class="o">=</span> <span class="n">Two</span> <span class="n">digit</span> <span class="n">month</span><span class="p">,</span> <span class="mi">01</span> <span class="o">=</span> <span class="n">January</span> <span class="n">dd</span> <span class="o">=</span> <span class="n">Two</span> <span class="n">digit</span> <span class="n">day</span> <span class="n">of</span> <span class="n">month</span><span class="p">,</span> <span class="mi">01</span> <span class="o">=</span> <span class="n">first</span> <span class="n">day</span> <span class="n">hh</span> <span class="o">=</span> <span class="n">Hour</span> <span class="n">of</span> <span class="n">day</span><span class="p">,</span> <span class="mi">00</span> <span class="o">-</span> <span class="mi">23</span> <span class="n">mm</span> <span class="o">=</span> <span class="n">Minute</span> <span class="n">of</span> <span class="n">hour</span><span class="p">,</span> <span class="mi">00</span> <span class="o">-</span> <span class="mi">59</span> <span class="n">ss</span> <span class="o">=</span> <span class="n">Second</span> <span class="n">of</span> <span class="n">minute</span><span class="p">,</span> <span class="mi">00</span> <span class="o">-</span> <span class="mi">59</span> <span class="n">S</span> <span class="o">=</span> <span class="n">Milliseconds</span> <span class="n">ZZ</span> <span class="o">=</span> <span class="n">Hours</span> <span class="n">of</span> <span class="n">timezone</span> <span class="n">offset</span> <span class="n">zz</span> <span class="o">=</span> <span class="n">Minutes</span> <span class="n">of</span> <span class="n">timezone</span> <span class="n">offset</span> </pre></div> </div> <p>If the timezone values are not present then the date time is interpreted to be in GMT.</p> <p>If the time portion of the date time is not present, then the time is assumed to be 00:00:00.0, i.e. the first millisecond of the specified date.</p> </div> <div class="section" id="message-body-in-put-or-post"> <h3>Message Body in PUT or POST<a class="headerlink" href="#message-body-in-put-or-post" title="Permalink to this headline">¶</a></h3> <p>Requests sent using the HTTP POST or PUT verbs MUST use MIME multipart-mixed encoding of the message body as described in <a class="reference external" href="http://tools.ietf.org/html/rfc2046#section-5.1.3">RFC2046</a>. In most cases and unless otherwise indicated, all parameters for PUT and POST requests except the authorization session will be sent in the message body (as opposed to URL parameters).</p> <p>Example of a HTTP POST request to the MN create() method using <em>curl</em>:</p> <div class="highlight-default"><div class="highlight"><pre><span></span><span class="n">curl</span> <span class="o">-</span><span class="n">X</span> <span class="n">POST</span> \ <span class="o">--</span><span class="n">cert</span> <span class="o">/</span><span class="n">tmp</span><span class="o">/</span><span class="n">x509up_u502</span> \ <span class="o">-</span><span class="n">H</span> <span class="s2">"Charset: utf-8"</span> \ <span class="o">-</span><span class="n">H</span> <span class="s2">"Content-Type: multipart/mixed; boundary=----------6B3C785C-6290-11DF-A355-A6ECDED72085_$"</span> \ <span class="o">-</span><span class="n">H</span> <span class="s2">"Accept: text/xml"</span> \ <span class="o">-</span><span class="n">H</span> <span class="s2">"User-Agent: pyd1/1.0 +http://dataone.org/"</span> \ <span class="o">-</span><span class="n">F</span> <span class="n">pid</span><span class="o">=</span><span class="mi">10</span><span class="n">Dappend1</span><span class="o">.</span><span class="n">txt</span> \ <span class="o">-</span><span class="n">F</span> <span class="nb">object</span><span class="o">=</span><span class="nd">@content</span><span class="o">.</span><span class="n">bin</span> \ <span class="o">-</span><span class="n">F</span> <span class="n">sysmeta</span><span class="o">=</span><span class="nd">@systemmetadata</span><span class="o">.</span><span class="n">abc</span> \ <span class="s2">"https://demo1.test.dataone.org/knb/d1/mn/v1/object"</span> </pre></div> </div> <p>Example serialized body of a HTTP POST request to the MN create() method (excluding session information):</p> <div class="highlight-default"><div class="highlight"><pre><span></span><span class="n">TODO</span> </pre></div> </div> </div> <div class="section" id="message-body-in-delete"> <h3>Message Body in DELETE<a class="headerlink" href="#message-body-in-delete" title="Permalink to this headline">¶</a></h3> <p><a class="reference external" href="http://tools.ietf.org/html/rfc2046#section-5.1.3">RFC2046</a> does not explicitly prevent the presence of a message body in a HTTP DELETE request, however support for transmission of the request payload may vary by technology. DELETE requests requiring a request payload MUST have accompanying integration tests that exercise the technologies involved.</p> </div> </div> </div> </div> </div> </div> <div class="sphinxsidebar" role="navigation" aria-label="main navigation"> <div class="sphinxsidebarwrapper"> <p class="logo"><a href="http://dataone.org"> <img class="logo" src="../_static/dataone_logo.png" alt="Logo"/> </a></p> <h3><a href="../index.html">Table Of Contents</a></h3> <ul> <li><a class="reference internal" href="#">REST Interface Overview</a><ul> <li><a class="reference internal" href="#message-serialization">Message Serialization</a></li> <li><a class="reference internal" href="#parameters-in-requests">Parameters in Requests</a><ul> <li><a class="reference internal" href="#session-information">Session Information</a></li> <li><a class="reference internal" href="#url-path-parameters">URL Path Parameters</a></li> <li><a class="reference internal" href="#url-query-parameters">URL Query Parameters</a></li> <li><a class="reference internal" href="#boolean-url-query-parameters">Boolean URL Query Parameters</a></li> <li><a class="reference internal" href="#date-parameters-in-urls">Date Parameters in URLs</a></li> <li><a class="reference internal" href="#message-body-in-put-or-post">Message Body in PUT or POST</a></li> <li><a class="reference internal" href="#message-body-in-delete">Message Body in DELETE</a></li> </ul> </li> </ul> </li> </ul> <h3>Related Topics</h3> <ul> <li><a href="../index.html">Documentation Overview</a><ul> <li><a href="index.html">DataONE APIs</a><ul> <li>Previous: <a href="index.html" title="previous chapter">DataONE APIs</a></li> <li>Next: <a href="MN_APIs.html" title="next chapter">Member Node APIs</a></li> </ul></li> </ul></li> </ul> <div id="searchbox" style="display: none" role="search"> <h3>Quick search</h3> <form class="search" action="../search.html" method="get"> <div><input type="text" name="q" /></div> <div><input type="submit" value="Go" /></div> <input type="hidden" name="check_keywords" value="yes" /> <input type="hidden" name="area" value="default" /> </form> </div> <script type="text/javascript">$('#searchbox').show(0);</script> </div> </div> <div class="clearer"></div> </div> <div class="footer"> <div id="copyright"> © Copyright <a href="http://www.dataone.org">2009-2017, DataONE</a>. [ <a href="../_sources/apis/rest_comms.txt" rel="nofollow">Page Source</a> | <a href='https://redmine.dataone.org/projects/d1/repository/changes/documents/Projects/cicore/architecture/api-documentation/source/apis/rest_comms.txt' rel="nofollow">Revision History</a> ] </div> <div id="acknowledgement"> <p>This material is based upon work supported by the National Science Foundation under Grant Numbers <a href="http://www.nsf.gov/awardsearch/showAward?AWD_ID=0830944">083094</a> and <a href="http://www.nsf.gov/awardsearch/showAward?AWD_ID=1430508">1430508</a>.</p> <p>Any opinions, findings, and conclusions or recommendations expressed in this material are those of the author(s) and do not necessarily reflect the views of the National Science Foundation.</p> </div> </div> <!-- <hr /> <div id="HCB_comment_box"><a href="http://www.htmlcommentbox.com">HTML Comment Box</a> is loading comments...</div> <link rel="stylesheet" type="text/css" href="_static/skin.css" /> <script type="text/javascript" language="javascript" id="hcb"> /*<! -*/ (function() {s=document.createElement("script"); s.setAttribute("type","text/javascript"); s.setAttribute("src", "http://www.htmlcommentbox.com/jread?page="+escape((typeof hcb_user !== "undefined" && hcb_user.PAGE)||(""+window.location)).replace("+","%2B")+"&mod=%241%24wq1rdBcg%24Gg8J5iYSHJWwAJtlYu/yU."+"&opts=21407&num=10"); if (typeof s!="undefined") document.getElementsByTagName("head")[0].appendChild(s);})(); /* ->*/ </script> --> </body> </html>