.. list-table:: Overview of APIs and the functions they implement :widths: 6 6 30 :header-rows: 1 * - Module - Function - Description * - :mod:`MNCore` - :func:`MNCore.ping` - Low level "are you alive" operation. A valid ping response is indicated by a HTTP status of 200. A timestmap indicating the current system time (UTC) on the node MUST be returned in the HTTP Date header. The Member Node should perform some minimal internal functionality testing before answering. However, ping checks will be frequent (every few minutes) so the internal functionality test should not be high impact. Any status response other than 200 indicates that the node is offline for DataONE operations. Note that the timestamp returned in the Date header should follow the semantics as described in the HTTP specifications, http://www.w3.org/Protocols/rfc2616/rfc2616-sec14.html#sec14.18 The response body will be ignored by the caller except in the case of an error, in which case the response body should contain the appropriate DataONE exception. Appears in functional use cases: :doc:`UC10 ` * - \ - :func:`MNCore.getLogRecords` - Retrieve log information from the Member Node for the specified slice parameters. Log entries will only return PIDs. This method is used primarily by the log aggregator to generate aggregate statistics for nodes, objects, and the methods of access. The response MUST contain only records for which the requestor has permission to read. Note that date time precision is limited to one millisecond. If no timezone information is provided UTC will be assumed. Access control for this method MUST be configured to allow calling by Coordinating Nodes and MAY be configured to allow more general access. v2.0: The event parameter has changed from :class:`v1_0.Types.Event` to a plain *string* v2.0: The structure of :class:`v2_0.Types.Log` has changed. * - \ - :func:`MNCore.getCapabilities` - Returns a document describing the capabilities of the Member Node. The response at the Member Node base URL is for convenience only. Clients of Member Nodes SHOULD use the /node URL to retrieve the node capabilities document. * - :mod:`MNRead` - :func:`MNRead.get` - Retrieve an object identified by *id* from the node. Supports both PIDs and SIDs. SID will return HEAD PID. The response MUST contain the bytes of the indicated object, and the checksum of the bytes retrieved SHOULD match the :attr:`SystemMetadata.checksum` recorded in the :class:`Types.SystemMetadata` when calling with PID. If the object does not exist on the node servicing the request, then :exc:`Exceptions.NotFound` must be raised even if the object exists on another node in the DataONE system. Also implmented by Coordinating Nodes as :func:`CNRead.get`. Appears in functional use cases: :doc:`UC01 `, :doc:`UC06 `, :doc:`UC16 ` * - \ - :func:`MNRead.getSystemMetadata` - Describes the object identified by *id* by returning the associated system metadata object. If the object does not exist on the node servicing the request, then :exc:`Exceptions.NotFound` MUST be raised even if the object exists on another node in the DataONE system. Appears in functional use cases: :doc:`UC06 `, :doc:`UC37 `, :doc:`UC16 ` * - \ - :func:`MNRead.describe` - This method provides a lighter weight mechanism than :func:`MNRead.getSystemMetadata` for a client to determine basic properties of the referenced object. The response should indicate properties that are typically returned in a HTTP HEAD request: the date late modified, the size of the object, the type of the object (the :attr:`SystemMetadata.formatId`). The principal indicated by *token* must have read privileges on the object, otherwise :exc:`Exceptions.NotAuthorized` is raised. If the object does not exist on the node servicing the request, then :exc:`Exceptions.NotFound` must be raised even if the object exists on another node in the DataONE system. Note that this method is likely to be called frequently and so efficiency should be taken into consideration during implementation. Appears in functional use cases: :doc:`UC16 ` * - \ - :func:`MNRead.getChecksum` - Returns a :class:`Types.Checksum` for the specified object using an accepted hashing algorithm. The result is used to determine if two instances referenced by a PID are identical, hence it is necessary that MNs can ensure that the returned checksum is valid for the referenced object either by computing it on the fly or by using a cached value that is certain to be correct. * - \ - :func:`MNRead.listObjects` - Retrieve the list of objects present on the MN that match the calling parameters. This method is required to support the process of :term:`Member Node synchronization`. At a minimum, this method MUST be able to return a list of objects that match:: fromDate < SystemMetadata.dateSysMetadataModified but is expected to also support date range (by also specifying *toDate*), and should also support slicing of the matching set of records by indicating the starting *index* of the response (where 0 is the index of the first item) and the *count* of elements to be returned. Note that date time precision is limited to one millisecond. If no timezone information is provided, the UTC will be assumed. Note that date time precision is limited to one millisecond. If no timezone information is provided, the UTC will be assumed. Appears in functional use cases: :doc:`UC06 `, :doc:`UC16 ` * - \ - :func:`MNRead.synchronizationFailed` - This is a callback method used by a CN to indicate to a MN that it cannot complete synchronization of the science metadata identified by *pid*. When called, the MN should take steps to record the problem description and notify an administrator or the data owner of the issue. A successful response is indicated by a HTTP status of 200. An unsuccessful call is indicated by a returned exception and associated HTTP status code. Access control for this method MUST be configured to allow calling by Coordinating Nodes and MAY be configured to allow more general access. Appears in functional use cases: :doc:`UC06 ` * - \ - :func:`MNRead.systemMetadataChanged` - Notifies the Member Node that the authoritative copy of system metadata on the Coordinating Nodes has changed. The Member Node SHOULD schedule an update to its information about the affected object by retrieving an authoritative copy from a Coordinating Node. Note that date time precision is limited to one millisecond. Access control for this method MUST be configured to allow calling by Coordinating Nodes. * - \ - :func:`MNRead.getReplica` - Called by a target Member Node to fullfill the replication request originated by a Coordinating Node calling :func:`MNReplication.replicate`. This is a request to make a replica copy of the object, and differs from a call to GET /object in that it should be logged as a replication event rather than a read event on that object. If the object being retrieved is restricted access, then a Tier 2 or higher Member Node MUST make a call to :func:`CNReplication.isNodeAuthorized` to verify that the Subject of the caller is authorized to retrieve the content. A successful operation is indicated by a HTTP status of 200 on the response. Failure of the operation MUST be indicated by returning an appropriate exception. Appears in functional use cases: :doc:`UC09 ` * - :mod:`MNAuthorization` - :func:`MNAuthorization.isAuthorized` - Test if the user identified by the provided session has authorization for operation on the specified object. A successful operation is indicated by a return HTTP status of 200. Failure is indicated by an exception such as :exc:`NotAuthorized` being returned. The body of the response is arbitrary and SHOULD be ignored by the caller. If the action is not authorized, then a :exc:`NotAuthorized` exception MUST be raised. .. Note:: Should perhaps add convenience methods for "canRead()" and "canWrite()" to verify that a user is able to read / write an object. Appears in functional use cases: :doc:`UC01 `, :doc:`UC37 ` * - :mod:`MNStorage` - :func:`MNStorage.create` - Called by a client to adds a new object to the Member Node. The *pid* must not exist in the DataONE system or should have been previously reserved using :func:`CNCore.reserveIdentifier`. A new, unique :attr:`Types.SystemMetadata.seriesId` may be included. The caller MUST have authorization to write or create content on the Member Node. Appears in functional use cases: :doc:`UC04 `, :doc:`UC09 `, :doc:`UC16 ` * - \ - :func:`MNStorage.update` - This method is called by clients to update objects on Member Nodes. Updates an existing object by creating a new object identified by *newPid* on the Member Node which explicitly obsoletes the object identified by *pid* through appropriate changes to the SystemMetadata of *pid* and *newPid*. The Member Node sets :attr:`Types.SystemMetadata.obsoletedBy` on the object being obsoleted to the *pid* of the new object. It then updates :attr:`Types.SystemMetadata.dateSysMetadataModified` on both the new and old objects. The modified system metadata entries then become available in :func:`MNRead.listObjects`. This ensures that a Coordinating Node will pick up the changes when filtering on :attr:`Types.SystemMetadata.dateSysMetadataModified`. The update operation MUST fail with :exc:`Exceptions.InvalidRequest` on objects that have the :attr:`Types.SystemMetadata.archived` property set to true. A new, unique :attr:`Types.SystemMetadata.seriesId` may be included when beginning a series, or a series may be extended if the newPid obsoletes the existing pid. Appears in functional use cases: :doc:`UC16 ` * - \ - :func:`MNStorage.generateIdentifier` - Given a scheme and optional fragment, generates an identifier with that scheme and fragment that is unique. Maybe be used for generating either PIDs or SIDs. The message body is encoded as MIME Multipart/form-data * - \ - :func:`MNStorage.delete` - Deletes an object managed by DataONE from the Member Node. Member Nodes MUST check that the caller (typically a Coordinating Node) is authorized to perform this function. The delete operation will be used primarily by Coordinating Nodes to help manage the number of replicas of an object that are present in the entire system. The operation removes the object from further interaction with DataONE services. The implementation may delete the object bytes, and in general should do so since a delete operation may be in response to a problem with the object (e.g. it contains malicious content, is innappropriate, or is the subject of a legal request). If the object does not exist on the node servicing the request, then an :exc:`Exceptions.NotFound` exception is raised. The message body of the exception SHOULD contain a hint as to the location of the :func:`CNRead.resolve` method. Appears in functional use cases: :doc:`UC16 ` * - \ - :func:`MNStorage.archive` - Hides an object managed by DataONE from search operations, effectively preventing its discovery during normal operations. The operation does not delete the object bytes, but instead sets the :attr:`Types.SystemMetadata.archived` flag to True. This ensures that the object can still be resolved (and hence remain valid for existing citations and cross references), though will not appear in searches. Objects that are archived can not be updated through the :func:`MNStorage.update` operation. Archived objects can not be un-archived. This behavior may change in future versions of the DataONE API. Member Nodes MUST check that the caller is authorized to perform this function. If the object does not exist on the node servicing the request, then an :exc:`Exceptions.NotFound` exception is raised. The message body of the exception SHOULD contain a hint as to the location of the :func:`CNRead.resolve` method. * - \ - :func:`MNStorage.updateSystemMetadata` - Provides a mechanism for updating system metadata for any objects held on the Member Node where that Member Node is the authoritative Member Node. Coordinating Node can call this method on the non-authoritative Member Node. However, this is not a normal operation and is for the special case - the authoritative Member Node doesn't exist any more. Coordinating Node calling the method on the non-authoriative Memember Node in the normal operation can cause an unexpected consequence. This method is typically used by Authoritative Member Node or rights holder[s] to ensure system metadata quality. * - :mod:`MNReplication` - :func:`MNReplication.replicate` - Called by a Coordinating Node to request that the Member Node create a copy of the specified object by retrieving it from another Member Nodeode and storing it locally so that it can be made accessible to the DataONE system. A successful operation is indicated by a HTTP status of 200 on the response. Failure of the operation MUST be indicated by returning an appropriate exception. Access control for this method MUST be configured to allow calling by Coordinating Nodes. Appears in functional use cases: :doc:`UC09 ` * - :mod:`MNQuery` - :func:`MNQuery.query` - Submit a query against the specified *queryEngine* and return the response as formatted by the queryEngine. The :func:`MNQuery.query` operation may be implemented by more than one type of search engine and the *queryEngine* parameter indicates which search engine is targeted. The value and form of *query* is determined by the specific query engine. For example, the SOLR search engine will accept many of the standard parameters of SOLR, including field restrictions and faceting. This method is optional for Member Nodes, but if implemented, both getQueryEngineDescription and listQueryEngines must also be implemented. Appears in functional use cases: :doc:`UC02 `, :doc:`UC16 ` * - \ - :func:`MNQuery.getQueryEngineDescription` - Provides metadata about the query service of the specified *queryEngine*. The metadata provides a brief description of the query engine, its version, its schema version, and an optional list of fields supported by the query engine. * - \ - :func:`MNQuery.listQueryEngines` - Returns a list of query engines, i.e. supported values for the *queryEngine* parameter of the *getQueryEngineDescription* and *query* operations. The list of search engines available may be influenced by the authentication status of the request. * - :mod:`MNView` - :func:`MNView.view` - Provides a formatted view of an object (science metadata, data, resource, or other) using the given named theme. If this service is implemented, the :func:`MNView.view` operation must implement at least one {theme} named 'default' to provide a standard (possibly minimalistic) view of the content in HTML format. If the {theme} parameter is not recognized, the service must render the object using the default theme rather than throwing an error. Note that the return type of Types.OctetStream requires that the consuming client has a priori knowledge of the theme being returned (like HTML). Response headers must include the correct mime-type of the view being returned. This method is optional for Member Nodes, but if implemented, MNView.listViews must also be implemented. * - \ - :func:`MNView.listViews` - Provides a list of usable themes for rendering content in a view, including a required 'default' theme. The list of themes is provided as an OptionList, where the option key should be used as the theme name in calls to MNView.view, and the description provides a human readable description of what will be returned fo rthat theme. This method is optional for Member Nodes, but if implemented, MNView.view must also be implemented. * - :mod:`MNPackage` - :func:`MNPackage.getPackage` - Provides all of the content of a DataONE data package as defined by an OAI-ORE document in DataONE, in one of several possible package serialization formats. The serialized package will contain all of the data described in the ORE aggregation. The default implementation will include packages in the BagIt format. The packageType formats must be specified using the associated ObjectFormat formatId for that package serialization format. The {id} parameter must be the identifier of an ORE package object. If it is the identifier of one of the science metadata documents or data files contained within the package, the Member Node should throw an InvalidRequest exception. Identifiers may be either PIDss or SIDs. This method is optional for Member Nodes. * - :mod:`CNCore` - :func:`CNCore.ping` - Low level "are you alive" operation. A valid ping response is indicated by a HTTP status of 200. A timestmap indicating the current system time (UTC) on the node MUST be returned in the HTTP Date header. The Member Node should perform some minimal internal functionality testing before answering. However, ping checks will be frequent (every few minutes) so the internal functionality test should not be high impact. Any status response other than 200 indicates that the node is offline for DataONE operations. Note that the timestamp returned in the Date header should follow the semantics as described in the HTTP specifications, http://www.w3.org/Protocols/rfc2616/rfc2616-sec14.html#sec14.18 The response body will be ignored by the caller expect in the case of an error, in which case the response body should contain the appropriate DataONE exception. Appears in functional use cases: :doc:`UC10 ` * - \ - :func:`CNCore.create` - Used internally within a Coordinating Node to add a new object to the object store. This method is not publicly exposed by a Coordinating Node. v2.0: The structure of :class:`v2_0.Types.SystemMetadata` has changed from Version 1. Appears in functional use cases: :doc:`UC04 `, :doc:`UC09 `, :doc:`UC16 ` * - \ - :func:`CNCore.listFormats` - Returns a list of all object formats registered in the DataONE Object Format Vocabulary. v2.0: The structure of :class:`v2_0.Types.ObjectFormat` has changed. * - \ - :func:`CNCore.getFormat` - Returns the object format registered in the DataONE Object Format Vocabulary for the given format identifier. v2.0: The structure of :class:`v2_0.Types.ObjectFormat` has changed. * - \ - :func:`CNCore.getLogRecords` - Retrieves consolidated log information for the specified date range (fromDate < timestamp <= toDate) for the entire DataONE infrastructure Note that date time precision is limited to one millisecond. If no timezone information is provided, the UTC will be assumed. Note that full access to log records requires access through a priviledged account. A public user may be presented with an empty response. v2.0: The structure of :class:`v2_0.Types.Log` has changed. v2.0: The event parameter has changed from :class:`v1_0.Types.Event` to a plain *string* Appears in functional use cases: :doc:`UC16 ` * - \ - :func:`CNCore.reserveIdentifier` - Reserves the identifier that is unique and can not be used by any other sessions. Future calls to :func:`MNStorage.create` and :func:`MNStorage.update` that reference this ID must be made by the same :term:`principal` making the reservation, otherwise an error is raised on those methods. The requested identifier is transmitted in a MIME Multipart/form-data body with *id* as key, and the identifier string as value. v2.0: The identifier being reserved may be used as a :term:`PID` or :term:`SID`. Appears in functional use cases: :doc:`UC16 ` * - \ - :func:`CNCore.generateIdentifier` - Given a scheme and optional fragment, generates an identifier with that scheme and fragment that is unique. Returned identifier may be used as either a PID or a SID. The message body is encoded as MIME Multipart/form-data Appears in functional use cases: :doc:`UC16 ` * - \ - :func:`CNCore.listChecksumAlgorithms` - Returns a list of checksum algorithms that are supported by DataONE. * - \ - :func:`CNCore.setObsoletedBy` - Updates the :attr:`Types.SystemMetadata.obsoletedBy` property for an object, indicating that the object specified by *pid* has been obsoleted by the identifier in *obsoletedByPid*. v2.0: Method implementation has changed to ensure that the obsolescence chain is consistent with use of any SID assigned to the object. * - \ - :func:`CNCore.delete` - Deletes an object from the entire DataONE system, including all nodes known to hold a copy of the object. The PID and/or SID of the object will continue to be shown as in use (preventing its reuse for other objects), however the object should not be resolvable (NotFound) or retrievable. The delete operation is used only by administrators in response to a request to remove an object from DataONE, perhaps because of legal requirements or the object has been identified as containing malicious content. Appears in functional use cases: :doc:`UC16 ` * - \ - :func:`CNCore.archive` - Hides an object managed by DataONE from search operations, effectively preventing its discovery during normal operations. The operation does not delete the object bytes, but instead sets the :attr:`Types.SystemMetadata.archived` flag to True. This ensures that the object can still be resolved (and hence remain valid for existing citations and cross references), though will not appear in searches. Objects that are archived can not be updated through the :func:`MNStorage.update` operation. Archived objects can not be un-archived. This behavior may change in future versions of the DataONE API. The CN should ensure that all MNs holding a copy of the object are informed of the change so that they may update their information about the object. v2.0: The supplied identifier may be a :term:`PID` or a :term:`SID`. * - \ - :func:`CNCore.listNodes` - Returns a list of nodes that have been registered with the DataONE infrastructure. v2.0: The structure of :class:`v2_0.Types.Node` has changed. Appears in functional use cases: :doc:`UC39 ` * - \ - :func:`CNCore.getCapabilities` - Returns a document describing the capabilities of the Coordinating Node. v2.0: The structure of :class:`v2_0.Types.Node` has changed. * - \ - :func:`CNCore.registerSystemMetadata` - Provides a mechanism for adding system metadata independently of its associated object, such as when adding system metadata for data objects. This method is used internally by Coordinating Nodes. v2.0: The structure of :class:`v2_0.Types.SystemMetadata` has changed. * - \ - :func:`CNCore.updateSystemMetadata` - Provides a mechanism for updating system metadata for any objects held in the federation. Usage of this method SHOULD be restricted to CNs for updating the system metadata in the underlying CN storage sub-system. v2.0: The structure of :class:`v2_0.Types.SystemMetadata` has changed. Note: the serial version and the replica list in the new system metadata will be ignored. * - \ - :func:`CNCore.hasReservation` - Checks to determine if the supplied *subject* is the owner of the reservation of *id*. A positive response (that the *pid* is reserved and owned by *subject*) is indicated by a return of a HTTP status of 200. A negative response is indicated by an exception and the associated HTTP status code. v2.0: The identifier may be a :term:`PID` or :term:`SID`. * - :mod:`CNRead` - :func:`CNRead.get` - Retrieves the object identified by *id* from the node. If the object is not present on the node, then an :exc:`Exceptions.NotFound` error is raised, regardless of whether the object exists on another node in the DataONE system. v2.0: The supplied identifier may be a :term:`PID` or a :term:`SID`. Appears in functional use cases: :doc:`UC01 `, :doc:`UC16 `, :doc:`UC09 ` * - \ - :func:`CNRead.getSystemMetadata` - Returns the :term:`system metadata` that contains DataONE specific information about the object identified by *id*. Authoritative copies of system metadata are only available from the Coordinating Nodes. v2.0: The supplied identifier may be a :term:`PID` or a :term:`SID` and the returned :class:`v2_0.Types.SystemMetadata` structure has changed. Appears in functional use cases: :doc:`UC36 `, :doc:`UC37 `, :doc:`UC16 ` * - \ - :func:`CNRead.describe` - This method provides a lighter weight mechanism than :func:`CNRead.getSystemMetadata` for a client to determine basic properties of the referenced object. The response should indicate properties that are typically returned in a HTTP HEAD request: the date late modified, the size of the object, the type of the object (the :attr:`SystemMetadata.formatId`). The principal indicated by *token* must have read privileges on the object, otherwise :exc:`Exceptions.NotAuthorized` is raised. If the object does not exist on the node servicing the request, then :exc:`Exceptions.NotFound` must be raised even if the object exists on another node in the DataONE system. Note that this method is likely to be called frequently and so efficiency should be taken into consideration during implementation. v2.0: The supplied identifier may be a :term:`PID` or a :term:`SID`. Appears in functional use cases: :doc:`UC16 ` * - \ - :func:`CNRead.resolve` - Returns a list of nodes (MNs or CNs) known to hold copies of the object identified by *id*. The object resolution process is intended to provide a simple mechanism for a client to discover from which node(s) a particular object may be retrieved. Details about method interfaces (i.e. REST URLs) exposed by a particular node can be determined by examining the response from the *node* collection. For convenience, the :func:`MNRead.get` URL is included in the response as is the base URL of the node REST services. Note also that the same functionality as *resolve()* can be implemented by retrieving a copy of the system metadata for the object and utilizing the node registry to discover the base URL from which the client can construct the *get()* URL. Resolve is provided for efficiency since the response size is much smaller. Resolve will return a HTTP status of 303 (see other) on success. The HTTP header "Location" MUST be set, and it's value SHOULD be the full get() URL for retrieving the object from the first location in the resolve response. v2.0: The supplied identifier may be a :term:`PID` or a :term:`SID`. If the identifier is a SID, then resolution is for the latest version of an object (i.e. the head of the obsolescence chain). Appears in functional use cases: :doc:`UC36 `, :doc:`UC16 ` * - \ - :func:`CNRead.getChecksum` - Returns the checksum for the specified object as reported in the system metadata. Note that the signature of this method differs from :func:`MNRead.getChecksum` as that method takes an optional algorithm parameter. Appears in functional use cases: :doc:`UC09 ` * - \ - :func:`CNRead.listObjects` - Retrieve the list of objects present on the CN that match the calling parameters. At a minimum, this method should be able to return a list of objects that match:: fromDate < SystemMetadata.dateSysMetadataModified but is expected to also support date range (by also specifying *toDate*), and should also support slicing of the matching set of records by indicating the starting *index* of the response (where 0 is the index of the first item) and the *count* of elements to be returned. Note that date time precision is limited to one millisecond. If no timezone information is provided, the UTC will be assumed. Note that date time precision is limited to one millisecond. If no timezone information is provided, the UTC will be assumed. V2.0: Added filter on authoritativeMemberNode value. Appears in functional use cases: :doc:`UC06 `, :doc:`UC16 ` * - \ - :func:`CNRead.search` - Search the metadata catalog and return identifiers of metadata records that match the criteria. Search may be implemented by more than one type of search engine. The queryType parameter indicates which search engine should be targeted. The value and form of *query* is determined by the search engine. Currently supported search engines include: "solr" Appears in functional use cases: :doc:`UC02 `, :doc:`UC16 ` * - \ - :func:`CNRead.query` - Submit a query against the specified *queryEngine* and return the response as formatted by the queryEngine. The *query()* operation may be implemented by more than one type of search engine and the *queryEngine* parameter indicates which search engine is targeted. The value and form of *query* is determined by the specific query engine. For example, the solr search engine will accept many of the standard parameters of solr, including field restrictions and faceting. v1.1: This method was added. Appears in functional use cases: :doc:`UC02 `, :doc:`UC16 ` * - \ - :func:`CNRead.getQueryEngineDescription` - Provides metadata about the query service of the specified *queryEngine*. The metadata provides a brief description of the query engine, its version, its schema version, and an optional list of fields supported by the query engine. v1.1: This method was added. * - \ - :func:`CNRead.listQueryEngines` - Returns a list of query engines, i.e. supported values for the *queryEngine* parameter of the *getQueryEngineDescription* and *query* operations. The list of search engines available may be influenced by the authentication status of the request. v1.1: This method was added. * - \ - :func:`CNRead.synchronize` - Indicates to the CN that a new or existing object identified by PID requires synchronization. Note that this operation is asynchronous, a successful return indicates that the synchronization task was successfully queued. This method may be called by any Member Node for new content or the authoritative Member Node for updates to existing content. The CN will schedule the synchronization task which will then be processed in the same way as content changes identified through the listObjects polling mechanism. v2.0: This method was added to the Version 2.0 API. * - :mod:`CNAuthorization` - :func:`CNAuthorization.setRightsHolder` - Changes ownership (RightsHolder) of the specified object to the :term:`subject` specified by `userId` v2.0: The supplied identifier may be a :term:`PID` or a :term:`SID`. Appears in functional use cases: :doc:`UC16 ` * - \ - :func:`CNAuthorization.isAuthorized` - Test if the user identified by the provided token has authorization for operation on the specified object. A successful operation is indicated by a return HTTP status of 200. Failure is indicated by an exception such as :exc:`NotAuthorized` being returned. A successful response is indicated by a response HTTP status of 200. The body of the response is arbitrary and SHOULD be ignored by the caller. If the action is not authorized, then a :exc:`NotAuthorized` exception MUST be raised. v2.0: The supplied identifier may be a :term:`PID` or a :term:`SID`. Appears in functional use cases: :doc:`UC01 `, :doc:`UC02 `, :doc:`UC36 `, :doc:`UC37 ` * - \ - :func:`CNAuthorization.setAccessPolicy` - Sets the access permissions for an object identified by *id*. Triggers a change to the system metadata modified time stamp. Successful completion of this operation is indicated by a HTTP response status code of 200. Unsuccessful completion of this operation MUST be indicated by returning an appropriate exception such as :exc:`NotAuthorized`. v2.0: The supplied identifier may be a :term:`PID` or a :term:`SID`. Appears in functional use cases: :doc:`UC16 ` * - :mod:`CNIdentity` - :func:`CNIdentity.registerAccount` - Create a new :term:`subject` in the DataONE system. Note that there should probably be a lot more metadata captured about the new user, and there should be a mechanism for specifying the default access control rules for the new account. Appears in functional use cases: :doc:`UC16 ` * - \ - :func:`CNIdentity.updateAccount` - Update an existing :term:`subject` in the DataONE system. The target subject is determined from subject provided in the URL. The use calling this method must have write access to the account details. Note that there should be a policy for verifying the details that change via this method. Appears in functional use cases: :doc:`UC16 ` * - \ - :func:`CNIdentity.verifyAccount` - Verify that the Person data associated with this Subject is a true representation of the real world person. This service can only be called by users who have an administrative role for the domain of users in question. A successful completion of this operation is indicated by returning a HTTP status of 200. An exeption MUST be returned if the account verification is not successful. * - \ - :func:`CNIdentity.getSubjectInfo` - Get the information about a Person (their equivalent identities, and the Groups to which they belong) or the Group (including members). Appears in functional use cases: :doc:`UC12 ` * - \ - :func:`CNIdentity.listSubjects` - List the subjects, including users, groups, and systems, that match search criteria. The list can be restricted to subjects whose identifier matches certain substrings, and the size of the resultset can be paged through. * - \ - :func:`CNIdentity.mapIdentity` - Create a new mapping between the two identities, asserting that they represent the same subject. Mapping identities with this method requires explicit authorization for the user given in the Session object. The caller must have made sure that the primary and secondary identities represent one and the same individual. Successful completion of the request is indicated by returning a HTTP status of 200. A failed request MUST be indicated by returning an appropriate exception and setting the response HTTP status accordingly. * - \ - :func:`CNIdentity.removeMapIdentity` - Removes a previously asserted identity mapping from the Subject in the Session to the Subject given by the parameter. The reciprocol mapping entry is also removed. A successful request is indicated by returning a HTTP status of 200. A failed request MUST be indicated by returning an appropriate exception and setting the response HTTP status accordingly. * - \ - :func:`CNIdentity.requestMapIdentity` - Request a new mapping between the authenticated identity in the session and the given identity, asserting that they represent the same subject. Mapping identities is a two-step process wherein a map request is made by a primary Subject and a subsequent (confirmation) map request is made by the secondary Subject. This ensures that mappings are performed only by those that have authority to do so. Successful completion of the request is indicated by returning a HTTP status of 200. A failed request MUST be indicated by returning an appropriate exception and setting the response HTTP status accordingly. * - \ - :func:`CNIdentity.confirmMapIdentity` - Confirms a previously initiated identity mapping. If subject A asserts that B is the same identity through :func:`CNIdentity.requestMapIdentity`, then this method is called by B to confirm that assertion. A successful request is indicated by returning a HTTP status of 200. A failed request MUST be indicated by returning an appropriate exception and setting the response HTTP status accordingly. * - \ - :func:`CNIdentity.getPendingMapIdentity` - Gets the SubjectInfo of a previously initiated identity mapping. A successful request is indicated by returning a HTTP status of 200. A failed request MUST be indicated by returning an appropriate exception and setting the response HTTP status accordingly. * - \ - :func:`CNIdentity.denyMapIdentity` - Denies a previously initiated identity mapping. If subject A asserts that B is the same identity through :func:`CNIdentity.requestMapIdentity`, then this method is called by B to deny that assertion. A successful request is indicated by returning a HTTP status of 200. A failed request MUST be indicated by returning an appropriate exception and setting the response HTTP status accordingly. * - \ - :func:`CNIdentity.createGroup` - Create a group with the given name. Groups are lists of subjects that allow all members of the group to be referenced by listing solely the subject name of the group. Group names must be unique within the DataONE system. Groups can only be modified by Subjects listed as rightsHolders. * - \ - :func:`CNIdentity.updateGroup` - Add members to the named group. Group members can be modified only by the original creator of the group, otherwise a NotAuthorized exception is thrown. Group members are provided as a list of subjects that replace the group membership. Successful completion of this operation is indicated by a HTTP response status code of 200. Unsuccessful completion of this operation MUST be indicated by returning an appropriate exception. * - :mod:`CNReplication` - :func:`CNReplication.setReplicationStatus` - Update the replication status of the system metadata, ensuring that the change is appropriate for the given state of system metadata. For example, a MN can not change the status to *COMPLETED* unless the CN previously requested replication of the object and the replications status of the object (as indicated in the system metadata) is set to *QUEUED*. Successful completion of this operation is indicated by a HTTP response status code of 200. Unsuccessful completion of this operation MUST be indicated by returning an appropriate exception. The nodeRef, status, and failure parameters are transmitted as part of the HTTP request body encoded as a MIME Multipart/form-data encoded payload. This method can be only called by Coordinating Nodes and trusted Member Nodes. Appears in functional use cases: :doc:`UC09 ` * - \ - :func:`CNReplication.updateReplicationMetadata` - Replaces the replica with matching nodeRef in the system metadata of the specified object. Adds a new replica if the nodeRef of passed in Replica is not already present. Changes the date sys meta modified. Successful completion of the operation is indicated by returning a HTTP status of 200. Failure of the operation MUST be indicated by returning an appropriate exception. This method can be only called by Coordinating Nodes. * - \ - :func:`CNReplication.setReplicationPolicy` - Updates the replication policy entry for an object by updating the system metadata. Successful completion of the operation is indicated by returning a HTTP status of 200. Failure of the operation MUST be indicated by returning an appropriate exception. v2.0: The identifier may be a :term:`PID` or :term:`SID`. * - \ - :func:`CNReplication.isNodeAuthorized` - Verifies that a replication event was initiated by a CN by comparing the target node's identifiying subject with a known list of scheduled replication tasks. Successful completion of the operation is indicated by returning a HTTP status of 200. Failure of the operation MUST be indicated by returning an appropriate exception. * - \ - :func:`CNReplication.deleteReplicationMetadata` - Removes the replication information for the specified node from the object system metadata identified by *pid*. Removal of replication metadata is necessary if the Member Node goes offline permanently or for an extended period, or when it is deeemed prudent to migrate an object from one node to another to address resource management issues. This method can be only called by Coordinating Nodes. * - :mod:`CNRegister` - :func:`CNRegister.updateNodeCapabilities` - For updating the capabilities of the specified node. Most information is replaced by information in the new node, however, the node identifier, nodeType, ping, syncrhonization.lastHarvested, and synchronization.lastCompleteHarvest are preserved from the existing entry. Services in the old record not included in the new Node will be removed. Successful completion of this operation is indicated by a HTTP response status code of 200. Unsuccessful completion of this operation MUST be indicated by returning an appropriate exception. v2.0: The structure of :class:`v2_0.Types.Node` has changed. * - \ - :func:`CNRegister.getNodeCapabilities` - For retrieving the capabilities of the specified node if it is registered on the Coordinating Node being called. v2.0: The structure of :class:`v2_0.Types.Node` has changed. * - \ - :func:`CNRegister.register` - Register a new node in the system. If the node already exists, then a :exc:`IdentifierNotUnique` exception MUST be returned. v2.0: The structure of :class:`v2_0.Types.Node` has changed. * - :mod:`CNView` - :func:`CNView.view` - Provides a formatted view of an object (science metadata, data, resource, or other) using the given named theme. The service :func:`CNView.view` operation will implement at least one {theme} named 'default' to provide a standard (possibly minimalistic) view of the content in HTML format. In addition, a CN may redirect a client to the view service of the authoritative Member Node for a PID if that node has implemented the :func:`MNView.view` service and implements a compatible theme. If the {theme} parameter is not recognized, the service must render the object using the default theme rather than throwing an error. Note that the return type of Types.OctetStream requires that the consuming client has a priori knowledge of the theme being returned (like HTML). Response headers must include the correct mime-type of the view being returned. v2.0: This method was added to the Version 2.0 API. * - \ - :func:`CNView.listViews` - Provides a list of usable themes for rendering content in a view, including a required 'default' theme. The list of themes is provided as an OptionList, where the option key should be used as the theme name in calls to MNView.view, and the description provides a human readable description of what will be returned fo rthat theme. v2.0: This method was added to the Version 2.0 API. * - :mod:`CNDiagnostic` - :func:`CNDiagnostic.echoCredentials` - Echo the credentials used to make the call. This method can be used to verify the client certificate is valid and contains the expected information. v2.0: This method was added to the Version 2.0 API. * - \ - :func:`CNDiagnostic.echoSystemMetadata` - Parse and echo the provided system metadata On successful parsing, a copy of the system metadata is returned, otherwise an exception is returned indicating an error condition. v2.0: This operation is new to version 2.0. * - \ - :func:`CNDiagnostic.echoIndexedObject` - Parse and echo the provided science metadata or resource map document. The response is governed by the type of object provided in the request, and on success is one or more documents that are the result of parsing for indexing. Since DataONE supports multiple types of query engine, the query engine to be used for parsing is specified in the request. The servce may terminate the POST operation if the size of the object is beyond a reasonable size. v2.0: This operation is new to version 2.0.