Coordinating Node APIs
----------------------

The service interfaces described here are exposed through the Coordinating
Node REST interface to support interactions with Member Nodes and DataONE
clients.

The following table provides a list of API methods exposed by Coordinating
Nodes.

:Tier: 

  The tier in which a method is grouped.

:Version: 

  Version of API method is available. The lowest version number indicates when
  the method was added. A version number in parentheses indicates the method is
  available in that version and is unchanged from the previous version. If more
  than one version number is present, then the method signature or functionality
  has changed between API versions. e.g. "1.0, 2.0" indicates that the method
  was first introduced in Version 1.0 and has been modified in Version 2.0.

:REST:

  The HTTP method and path relative to the Base URL. Parameters specified in the
  URL are indicatd by braces. Note that parameters included in a path MUST be
  properly path encoded, and parameters included as key, value pairs MUST also
  be properly encoded.

:Function:

  The function name, associated with an API grouping.

:Parameters:

  Indicates the parameters used when calling the method (sent in the message
  payload) and the return type.


.. include:: generated/generated_CN_function_table.txt


Diagnostic API
~~~~~~~~~~~~~~

.. module:: CNDiagnostic
   :synopsis: Operations to assist with diagnosing authentication and content 
     formatting.

.. include:: generated/generated_CNDiagnostic.txt


Core API
~~~~~~~~

.. module:: CNCore
   :synopsis: Core operations necessary for basic interaction with
     Coordinating Nodes

.. include:: generated/generated_CNCore.txt


Read API
~~~~~~~~

.. module:: CNRead
   :synopsis: Data read operations for Coordinating Nodes

The *CN_read* API implements methods that enable object retrieval operations
on a :term:`Coordinating Node`. It includes searches of science metadata and
system metadata and exposes log records held by CNs.

.. include:: generated/generated_CNRead.txt

View API
~~~~~~~~

.. module:: CNView
   :synopsis: View operations to see formatted versions of metadata and data for Coordinating Nodes

The *CNView* API implements methods that enable viewing content 
on a :term:`Coordinating Node`. Like the MNView service, the CNView service provides a transformed view of a metadata file, data file, or package.  The CNView service provides a default view for all content, and may choose to redirect a review request to the authoritative Member Node for a given PID. 

.. include:: generated/generated_CNView.txt


Authorization API
~~~~~~~~~~~~~~~~~

.. module:: CNAuthorization
   :synopsis: Methods for authorization and access control

.. include:: generated/generated_CNAuthorization.txt


Identity API
~~~~~~~~~~~~

.. module:: CNIdentity
   :synopsis: Methods for account management and identity mapping.

.. include:: generated/generated_CNIdentity.txt


Replication API
~~~~~~~~~~~~~~~

.. module:: CNReplication
   :synopsis: 
     Supports operations for replication of content between Member Nodes.


The Data Replication API operates in conjunction with the
:mod:`MNReplication` API to assist with the replication of data and
science metadata content between Member Nodes to ensure that copies of data
and metadata can be retrieved from more than one Member Node where possible.

.. include:: generated/generated_CNReplication.txt

..
  
  This old stuff is commented out but kept here for revisiting later
  .. function:: getDefaultReplicationPolicy (sess)

  .. function:: getMNReplicateList()

  .. function:: getReplicationPolicy (sess, ID)

  .. function:: isReplicationNeeded ()

  .. function:: replicateMetadata ()

  .. function:: setDefaultReplicationPolicy (sess, policy)

  .. function:: setReplicationPolicy (sess, policy, ID)



Register API
~~~~~~~~~~~~

.. module:: CNRegister
   :synopsis: Register nodes and their capabilities, retrieve node list

The register API methods are used to maintain a registry of nodes participating
in the DataONE infrastructure.

Note that the node registry is much the same as the Object collection with a
restriction on the returned object formats to be Member Nodes or Coordinating
Nodes. It may be prudent for the implementation of the registration API to
leverage the existing functionality of the object collection rather than
implementing a parallel data store. In this case, the "science metadata" could
be a DC description of the node, and the "data" might be the detailed
registration information including node capabilities, scheduling and so forth.


.. include:: generated/generated_CNRegister.txt


..
  xxxx notes xxxx


  .. function:: addNodeCapabilities (nodeID, capabilities) -> boolean

     Adds the supplied capabilities to the system metadata describing the Member Node.

     :param nodeID: A PID that identifies the Member Node.

     :param capabilities: 
       A capabilities document that describes the resources and supported
       services of the Member Node.

     :returns: True if the operation succeeds

     :rtype: Boolean


  .. function:: register (token, capabilitiesURL) -> boolean

     Used to register a new Member Node.

     :param token: An authentication token with priviledges to rgister a new Member Node.

     :param capabilitiesURL: The URL from which capabilities will be retrieved.

     :raises exceptions.NotAuthorized: The supplied identity does not have
       authority to register a node.

     :raises Exceptions.NotFound: The supplied capabilitiesURL does not resolve
       to a capabilities document

     :rtype: Boolean

     :returns: True if the registration operation succeeds



  .. function:: registerForNotification (token, dataOwnerID)



  .. function:: verifyCapabilities (nodeID, capabilities) -> boolean

     Evaluates the supplied capabilities document. This may involve additional
     interaction with the MN as various aspects are evaluated.


  .. todo:: 
     The :func:`verifyCapabilities` will need to check functionality of the MN so
     need to define a few service hooks for checking these properties.


  State of Health API
  ~~~~~~~~~~~~~~~~~~~

  The Health API contains methods for determining the status of the DataONE
  infrastructure, including both the CNs and MNs.

  .. module:: CN_health
     :synopsis: Methods for reporting on the state of health of a CN and on the entire DataONE infrastructure

  :: 

    generateReport(token) -> statusReport


  .. function:: actOnPendingEvent (event)

  .. function:: reportPendingEvent (event)

  .. function:: Admin Application

  .. function:: notify (adminID, nodeID, service)


  .. function:: generateReport(token) -> statusReport

     Returns a status report for all of the registered Member Nodes. The
     informatio returned is used to give administrators information necessary to
     maintain the infrastructure.

     .. note:: 
        This method is used by Use Case 10 "MN Status Reports" for V0.3. However
        instead of a complete set of detailed status reports, the V0.3
        implementation of the use case will utilize the ``MN_health.heartbeat()``
        method to compile very basic information about the MNs. Later versions of
        this method will use the richer ``MN_health.getStatus(token)`` method.

     :param token: Identity with authority to generate reports.
   
     :rtype: Status report, ideally in XML + stylsheet or at least XHTML.