<!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>Proposal for API Refactoring &#8212; 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="License and Copyright Policy" href="../license_and_copyright_policy.html" />
    <link rel="prev" title="Time and Bandwidth Constraints" href="time_bandwidth_constraints.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="../license_and_copyright_policy.html" title="License and Copyright Policy"
             accesskey="N">next</a> |</li>
        <li class="right" >
          <a href="time_bandwidth_constraints.html" title="Time and Bandwidth Constraints"
             accesskey="P">previous</a> |</li>
        <li class="nav-item nav-item-0"><a href="../index.html"></a> &#187;</li>
          <li class="nav-item nav-item-1"><a href="index.html" accesskey="U">General Design and Implementation Notes</a> &#187;</li> 
      </ul>
    </div>  

    <div class="document">
      <div class="documentwrapper">
        <div class="bodywrapper">
          <div class="body">
            
  <div class="section" id="proposal-for-api-refactoring">
<h1>Proposal for API Refactoring<a class="headerlink" href="#proposal-for-api-refactoring" title="Permalink to this headline">¶</a></h1>
<p>The DataONE service APIs currently contain methods that are grouped by the
general category of functionality provided. For example, the CRUD API contains
methods that support create, read, update, and delete operations against the
Member Nodes. Such a grouping is convenient for development activities,
however does not relate well to the overall functionality that must be
expressed by a Member Node to participate at different &#8220;tiers&#8221; within the
DataONE federation. A particular MN might operate in a read-only manner and so
must express only a small selection of methods pulled from several different
APIs as they are currently defined.</p>
<p>Further complicating the division of methods between APIs is the need to
support versioning of services. Current versioning operates across the entire
set of APIs and thus requires that a service implements all methods of a
single version. A more granular approach would versioning at the API level, so
that in many cases (where there are no inter-dependencies) it will be possible
to update a set of methods without affecting other methods, and so service
update on a particular node can be more progressive, and so less disruptive to
ongoing operations.</p>
<p>Grouping the methods into API definitions more aligned with the functionality
that should be exposed by different classes or tiers of nodes should also
simplify the overall process of node service updates since the entire group of
methods can be updated rather than working with methods pulled from different
method groups of different versions to define the service that must be
implemented by a particular Member Node.</p>
<p>This document outlines a strategy for refactoring the APIs to better align
with the tiers of Member Nodes that are likely to participate in the DataONE
federation.</p>
<div class="section" id="member-node-tiers">
<h2>Member Node Tiers<a class="headerlink" href="#member-node-tiers" title="Permalink to this headline">¶</a></h2>
<p>Five tiers of Member Node functionality have currently been identified:</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">Tier 1:</th><td class="field-body">Public read, no Authn/Authz</td>
</tr>
<tr class="field-even field"><th class="field-name">Tier 2:</th><td class="field-body">Read/Resolve with Authn/Authz</td>
</tr>
<tr class="field-odd field"><th class="field-name">Tier 3:</th><td class="field-body">Write (create, update, delete), possibly limited support for data types</td>
</tr>
<tr class="field-even field"><th class="field-name">Tier 4:</th><td class="field-body">Limited Replication target (specified data types)</td>
</tr>
<tr class="field-odd field"><th class="field-name">Tier 5:</th><td class="field-body">Replication target, any data types</td>
</tr>
</tbody>
</table>
<p>The methods that must be supported by each of these are indicated in Table 1.</p>
<table border="1" class="docutils" id="id1">
<caption><span class="caption-text"><strong>Table 1.</strong> DataONE service methods supported at different
             tiers of Member Node functionality. (*)Authentication and
             Authorization APIs are under active development and may change
             from the specifications listed here.</span><a class="headerlink" href="#id1" title="Permalink to this table">¶</a></caption>
<colgroup>
<col width="8%" />
<col width="8%" />
<col width="8%" />
<col width="77%" />
</colgroup>
<thead valign="bottom">
<tr class="row-odd"><th class="head">Tier</th>
<th class="head">Existing APIs</th>
<th class="head">Proposed API</th>
<th class="head">Methods</th>
</tr>
</thead>
<tbody valign="top">
<tr class="row-even"><td>Core</td>
<td>MN_health, MN_crud</td>
<td>MN_core</td>
<td>ping, getCapabilities, getStatus, [getObjectStatistics],
[getOperationStatistics], [getLogRecords]</td>
</tr>
<tr class="row-odd"><td>Tier 1</td>
<td>MN_crud, MN_replication, MN_health</td>
<td>MN_read</td>
<td>get, getSystemMetadata, listObjects, describe, getChecksum,
synchronizationFailed</td>
</tr>
<tr class="row-even"><td>Tier 2</td>
<td>MN_authorization, MN_authentication</td>
<td>MN_auth</td>
<td>MNCore + login(*), logout(*), isAuthorized(*), setAccess(*)</td>
</tr>
<tr class="row-odd"><td>Tier 3</td>
<td>MN_crud</td>
<td>MN_storage</td>
<td>MNAuth + create, update, delete,</td>
</tr>
<tr class="row-even"><td>Tier 4</td>
<td>MN_replication</td>
<td>MN_replication</td>
<td>MNStorage + replicate</td>
</tr>
<tr class="row-odd"><td>Tier 5</td>
<td>&nbsp;</td>
<td>&nbsp;</td>
<td>MNReplicationCore (no additional methods)</td>
</tr>
</tbody>
</table>
</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="#">Proposal for API Refactoring</a><ul>
<li><a class="reference internal" href="#member-node-tiers">Member Node Tiers</a></li>
</ul>
</li>
</ul>
<h3>Related Topics</h3>
<ul>
  <li><a href="../index.html">Documentation Overview</a><ul>
  <li><a href="index.html">General Design and Implementation Notes</a><ul>
      <li>Previous: <a href="time_bandwidth_constraints.html" title="previous chapter">Time and Bandwidth Constraints</a></li>
      <li>Next: <a href="../license_and_copyright_policy.html" title="next chapter">License and Copyright Policy</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">
      &copy; Copyright <a href="http://www.dataone.org">2009-2017, DataONE</a>.
        [ <a href="../_sources/notes/api_refactoring.txt"
               rel="nofollow">Page Source</a> |
          <a href='https://redmine.dataone.org/projects/d1/repository/changes/documents/Projects/cicore/architecture/api-documentation/source/notes/api_refactoring.txt'
            rel="nofollow">Revision History</a> ]&nbsp;&nbsp;
      </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>