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. .. include:: generated/generated_CN_function_table.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 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.