DataONE APIs
============

The DataONE infrastructure exposes application programming interfaces (APIs)
that support interaction between :term:`Member Node` and :term:`Coordinating
Node`, and to support development of applications that interact with the
DataONE infrastructure (elements of the :term:`Investigator Toolkit`).


.. figure:: images/componentMethods.png 
   :figwidth: 100%

   *Figure 1.* Overview of the system components and the methods being called
   by each component. An arrow to a target indicates the origin is calling the
   method on the target.

All services in DataONE are implemented using a RESTful approach with HTTP as
the transport protocol and XML for encoding messages.

A Member Node provides content to the federation, and there are two main
technical aspects to Member Node participation in DataONE - the service
interfaces to be implemented (i.e. the Member Node APIs), and the content that
is to be served. At a fundamental level, all content in DataONE is treated as
discrete, immutable objects, each of which has a unique identifier. A Member
Node would be considered functionally complete if it were able to support the
required services interfaces for Tier 1 participation (i.e. public access,
read only content), and so enable the discovery of all objects available on
the Member Node (through listObjects), low level description of each object
(through getSystemMetadata), and retrieval of the object given it's identifier
(get).

There are basically three types of object being processed by DataONE: data objects, science metadata objects, and resource map documents. Each of these are uniquely identifiable by their unique identifier (PID), and each has associated System Metadata which describes the type, size, and so forth of the object.

Data objects are treated as opaque blobs. The object availability is registered by the coordinating nodes, and the blob is retrievable via the get method given its identifier.

Science metadata objects are metadata documents such as EML, FGDC, ISO19115 and so forth that provide metadata describing some data object(s). These are represented in XML according to their respective schema.

Resource Maps describe the relationships between data and metadata - they are basically RDF documents that conform to the OAI-ORE specifications.

From an object or class inheritance perspective, science metadata and resource maps might be considered specializations of the data object type in that more functionality is provided to DataONE by those types of object.

From a purely technical perspective, a Member Node may be completely functional and not provide any metadata or resource map documents. It will mean that the content provided will not be discoverable through the search interfaces.




Member Nodes can expose different levels of functionality that equate to four
different tiers while participating in the DataONE network. The tiers and Member
Node APIs necessary to support are summarized in the table below. Also indicated
are the corresponding Coordinating Node APIs that are necessary for
functionality expressed for each tier.

.. list-table::
   :widths: 1 5 5 5
   :header-rows: 1
   
   * - Tier
     - Description
     - MN APIs
     - CN APIs
   * - 1
     - Public read, no authentication or access control of content. No content
       can be created through the DataONE service interfaces. The node can not
       act as a replication target.
     - :mod:`MNCore`, :mod:`MNRead`
     - :mod:`CNCore`, :mod:`CNRead`
   * - 2
     - Read and resolve with access control support.
     - Tier 1 + :mod:`MNAuthorization`
     - :mod:`CNAuthorization`, :mod:`CNRegister`, :mod:`CNIdentity`
   * - 3
     - Write (create, update, delete), possibly limited support for data types
     - Tier 2 + :mod:`MNStorage`
     - 
   * - 4
     - Replication target. The types of content supported by the node may be
       limited to a subset of object formats.
     - Tier 3 + :mod:`MNReplication`
     - :mod:`CNReplication`

The specific methods that must be implemented for each tier are listed in the
respective APIs.


**Contents**

.. toctree::
   :maxdepth: 1
   
   REST_overview
   MN_APIs
   CN_APIs
   ITK_APIs
   Types
   Types_SAML
   Exceptions
   monitoring
   CN_internal_APIs