The service interfaces described here are exposed through the Coordinating Node REST interface to support interactions with Member Nodes and DataONE clients.
Coordinating Node operations to assist clients with diagnosing authentication and content formatting.
echoCredentials |
GET /diag/subject Echo the credentials used to make the call. |
echoIndexedObject |
POST /diag/object Parse and echo the provided science metadata or resource map document. |
echoSystemMetadata |
POST /diag/sysmeta Parse and echo the provided system metadata |
CNDiagnostic.
echoCredentials
(session)¶GET /diag/subject
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.
Version: | 2.0 |
---|---|
REST URL: |
|
Parameters: | session (Types.Session) – Session information that contains the identity of the calling user as retrieved from the X.509 certificate. Transmitted as part of the SSL handshake process. |
Returns: | The subjects and groups parsed from the supplied session information. |
Return type: | |
Raises: |
|
Example
Todo
Example for CNDiagnostic.echoCredentials
CNDiagnostic.
echoIndexedObject
(session, queryEngine, sysmeta, object)¶POST /diag/object
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.
Version: | 2.0 |
---|---|
REST URL: |
|
Parameters: |
|
Returns: | A document representing the parsed object as it would be prior to being added to a search index. For the solr query engine for example, this would be the equivalent of a <add><doc> .. </doc> .. </add> structure with possibly multiple documents. |
Return type: | |
Raises: |
|
Example
Todo
Example for CNDiagnostic.echoIndexedObject
CNDiagnostic.
echoSystemMetadata
(session, sysmeta)¶POST /diag/sysmeta
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.
Version: | 2.0 |
---|---|
REST URL: |
|
Parameters: |
|
Returns: | A copy of the supplied System Metadata. |
Return type: | |
Raises: |
|
Example
Todo
Example for CNDiagnostic.echoSystemMetadata
Core operations necessary for basic interaction with Coordinating Nodes.
archive (session, id) |
PUT /archive/{id} Hides an object managed by DataONE from search operations, effectively preventing its discovery during normal operations. |
create (session, pid, object, sysmeta) |
POST /object Used internally within a Coordinating Node to add a new object to the object store. |
delete (session, id) |
DELETE /object/{id} Deletes an object from the entire DataONE system, including all nodes known to hold a copy of the object. |
generateIdentifier (session, scheme[, fragment]) |
POST /generate Given a scheme and optional fragment, generates an identifier with that scheme and fragment that is unique. |
getCapabilities () |
GET / Returns a document describing the capabilities of the Coordinating Node. |
getFormat (formatId) |
GET /formats/{formatId} Returns the object format registered in the DataONE Object Format Vocabulary for the given format identifier. |
getLogRecords (session[, fromDate, toDate, …]) |
GET /log?[fromDate={fromDate}][&toDate={toDate}][&event={event}][&idFilter={idFilter}][&start={start}][&count={count}] Retrieves consolidated log information for the specified date range (fromDate < timestamp <= toDate) for the entire DataONE infrastructure |
hasReservation (session, subject, id) |
GET /reserve/{id}?subject={subject} Checks to determine if the supplied subject is the owner of the reservation of id. |
listChecksumAlgorithms () |
GET /checksum Returns a list of checksum algorithms that are supported by DataONE. |
listFormats () |
GET /formats Returns a list of all object formats registered in the DataONE Object Format Vocabulary. |
listNodes () |
GET /node Returns a list of nodes that have been registered with the DataONE infrastructure. |
ping () |
GET /monitor/ping Low level “are you alive” operation. |
registerSystemMetadata (session, pid, sysmeta) |
POST /meta Provides a mechanism for adding system metadata independently of its associated object, such as when adding system metadata for data objects. |
reserveIdentifier (session, id) |
POST /reserve Reserves the identifier that is unique and can not be used by any other sessions. |
setObsoletedBy (session, pid, obsoletedByPid, …) |
PUT /obsoletedBy/{pid} Updates the Types.SystemMetadata.obsoletedBy property for an object, indicating that the object specified by pid has been obsoleted by the identifier in obsoletedByPid. |
updateSystemMetadata (session, pid, sysmeta) |
PUT /meta Provides a mechanism for updating system metadata for any objects held in the federation. |
CNCore.
archive
(session, id)¶PUT /archive/{id}
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 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 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 PID or a SID.
Note: This method is private to the CNs and is not available on the public API.
Version: | 1.0, 2.0 |
---|---|
REST URL: |
|
Parameters: |
|
Returns: | The identifier of the object that was archived. |
Return type: | |
Raises: |
|
Example
Todo
Example for CNCore.archive
CNCore.
create
(session, pid, object, sysmeta)¶POST /object
Used internally within a Coordinating Node to add a new object to the object store.
Note: This method is private to the CNs and is not available on the public API.
v2.0: The structure of v2_0.Types.SystemMetadata
has changed from Version 1.
Version: | 1.0, 2.0 |
---|---|
Use Cases: | |
REST URL: |
|
Parameters: |
|
Returns: | The identifier that was used to insert the document into the system. This should be the same as the identifier provided as the pid parameter. |
Return type: | |
Raises: |
|
Example
Todo
Example for CNCore.create
CNCore.
delete
(session, id)¶DELETE /object/{id}
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.
Note: This method is private to the CNs and is not available on the public API.
Version: | 1.0, (2.0) |
---|---|
Use Cases: | |
REST URL: |
|
Parameters: |
|
Returns: | The identifier of the object that was deleted. |
Return type: | |
Raises: |
|
Example
Todo
Example for CNCore.delete
CNCore.
generateIdentifier
(session, scheme, fragment=None)¶POST /generate
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
Version: | 1.0, (2.0) |
---|---|
Use Cases: | |
REST URL: |
|
Parameters: |
|
Returns: | The identifier that was generated |
Return type: | |
Raises: |
|
Example
Todo
Example for CNCore.generateIdentifier
CNCore.
getCapabilities
()¶GET /
Returns a document describing the capabilities of the Coordinating Node.
v2.0: The structure of v2_0.Types.Node
has changed.
Version: | 1.0, 2.0 |
---|---|
REST URL: |
|
Returns: | The technical capabilities of the Coordinating Node |
Return type: | |
Raises: |
|
Example
Todo
Example for CNCore.getCapabilities
CNCore.
getFormat
(formatId)¶GET /formats/{formatId}
Returns the object format registered in the DataONE Object Format Vocabulary for the given format identifier.
v2.0: The structure of v2_0.Types.ObjectFormat
has changed.
Version: | 1.0, 2.0 |
---|---|
REST URL: |
|
Parameters: | formatId (Types.ObjectFormatIdentifier) – Unique ObjectFormatIdentifier for the object format Transmitted as part of the URL path and must be escaped accordingly. |
Returns: | The object format registered in the DataONE Object Format Vocablulary |
Return type: | |
Raises: |
|
Example
Retrieve information about the http://www.openarchives.org/ore/terms
formatId. Note that formatId has characters that should be escaped when added
as a URL path element. This is done here using a urlencode script.
1 2 3 4 5 6 7 8 9 10 11 | FORMATID=$(echo "http://www.openarchives.org/ore/terms" | urlencode)
#encoded formatid: http%3A%2F%2Fwww.openarchives.org%2Fore%2Fterms
curl -s "https://cn.dataone.org/cn/v2/formats/${FORMATID}" | xml fo
<?xml version="1.0" encoding="UTF-8"?>
<d1:objectFormat xmlns:d1="http://ns.dataone.org/service/types/v1">
<formatId>http://www.openarchives.org/ore/terms</formatId>
<formatName>Object Reuse and Exchange Vocabulary</formatName>
<formatType>RESOURCE</formatType>
</d1:objectFormat>
|
CNCore.
getLogRecords
(session, fromDate=None, toDate=None, event=None, idFilter=None, start=0, count=None)¶GET /log?[fromDate={fromDate}][&toDate={toDate}][&event={event}][&idFilter={idFilter}][&start={start}][&count={count}]
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 v2_0.Types.Log
has changed.
v2.0: The event parameter has changed from v1_0.Types.Event
to a plain string
Version: | 1.0, 2.0 |
---|---|
Use Cases: | |
REST URL: |
|
Parameters: |
|
Returns: | |
Return type: | |
Raises: |
|
Example
Todo
Example for CNCore.getLogRecords
CNCore.
hasReservation
(session, subject, id)¶GET /reserve/{id}?subject={subject}
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 PID or SID.
Version: | 1.0, 2.0 |
---|---|
REST URL: |
|
Parameters: |
|
Returns: | True - subject has the reservation on the PID; False - the PID does not exist; False - the PID is already in use; False - the PID is reserved by somone else. |
Return type: | boolean |
Raises: |
|
Example
Todo
Example for CNCore.hasReservation
CNCore.
listChecksumAlgorithms
()¶GET /checksum
Returns a list of checksum algorithms that are supported by DataONE.
Version: | 1.0, (2.0) |
---|---|
REST URL: |
|
Returns: | A list of supported checksum algorithms. |
Return type: | |
Raises: |
|
Example
Todo
Example for CNCore.listChecksumAlgorithms
CNCore.
listFormats
()¶GET /formats
Returns a list of all object formats registered in the DataONE Object Format Vocabulary.
v2.0: The structure of v2_0.Types.ObjectFormat
has changed.
Version: | 1.0, 2.0 |
---|---|
REST URL: |
|
Returns: | The list of object formats registered in the DataONE Object Format Vocabulary |
Return type: | |
Raises: |
|
Example
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 | curl -s "http://cn.dataone.org/cn/v2/formats"
<?xml version="1.0" encoding="UTF-8" standalone="yes"?><?xml-stylesheet type="text/xsl" href="/cn/xslt/dataone.types.v2.xsl" ?>
<ns3:objectFormatList xmlns:ns2="http://ns.dataone.org/service/types/v1"
xmlns:ns3="http://ns.dataone.org/service/types/v2.0"
count="132" start="0" total="132">
<objectFormat>
<formatId>eml://ecoinformatics.org/eml-2.0.0</formatId>
<formatName>Ecological Metadata Language, version 2.0.0</formatName>
<formatType>METADATA</formatType>
<mediaType name="text/xml"/>
<extension>xml</extension>
</objectFormat>
<objectFormat>
<formatId>eml://ecoinformatics.org/eml-2.0.1</formatId>
<formatName>Ecological Metadata Language, version 2.0.1</formatName>
<formatType>METADATA</formatType>
<mediaType name="text/xml"/>
<extension>xml</extension>
</objectFormat>
<objectFormat>
<formatId>eml://ecoinformatics.org/eml-2.1.0</formatId>
<formatName>Ecological Metadata Language, version 2.1.0</formatName>
<formatType>METADATA</formatType>
<mediaType name="text/xml"/>
<extension>xml</extension>
</objectFormat>
...
</ns3:objectFormatList>
|
CNCore.
listNodes
()¶GET /node
Returns a list of nodes that have been registered with the DataONE infrastructure.
v2.0: The structure of v2_0.Types.Node
has changed.
Version: | 1.0, 2.0 |
---|---|
Use Cases: | |
REST URL: |
|
Returns: | List of nodes from the registry |
Return type: | |
Raises: |
|
Example
List nodes registered with the Coordinating Nodes. The response is lengthy, only a portion is shown here.
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 34 35 36 37 38 39 40 41 42 43 44 45 46 47 48 49 50 51 52 53 54 55 56 57 58 59 60 61 62 63 64 65 66 67 68 69 70 71 72 73 74 75 76 | curl -s "http://cn.dataone.org/cn/v2/node"
<?xml version="1.0" encoding="UTF-8"?>
<?xml-stylesheet type="text/xsl" href="/cn/xslt/dataone.types.v2.xsl" ?>
<ns3:nodeList xmlns:ns2="http://ns.dataone.org/service/types/v1"
xmlns:ns3="http://ns.dataone.org/service/types/v2.0">
<node replicate="false" synchronize="false" type="cn" state="up">
<identifier>urn:node:CN</identifier>
<name>cn</name>
<description>Round Robin Router for Production Coordinating Nodes</description>
<baseURL>https://cn.dataone.org/cn</baseURL>
<services>
<service name="CNCore" version="v1" available="true"/>
<service name="CNRead" version="v1" available="true"/>
<service name="CNAuthorization" version="v1" available="true"/>
<service name="CNIdentity" version="v1" available="true">
<restriction methodName="mapIdentity">
<subject>CN=urn:node:KNB,DC=dataone,DC=org</subject>
</restriction>
</service>
<service name="CNReplication" version="v1" available="true"/>
<service name="CNRegister" version="v1" available="true"/>
<service name="CNCore" version="v2" available="true"/>
<service name="CNRead" version="v2" available="true"/>
<service name="CNAuthorization" version="v2" available="true"/>
<service name="CNIdentity" version="v2" available="true"/>
<service name="CNReplication" version="v2" available="true"/>
<service name="CNRegister" version="v2" available="true"/>
<service name="CNDiagnostic" version="v2" available="true"/>
<service name="CNView" version="v2" available="true"/>
</services>
<subject>CN=urn:node:CN,DC=dataone,DC=org</subject>
<contactSubject>CN=Robert P Waltz A904,O=Google,C=US,DC=cilogon,DC=org</contactSubject>
<property key="CN_operational_status">operational</property>
<property key="CN_node_name">CN</property>
</node>
...
<node replicate="true" synchronize="true" type="mn" state="up">
<identifier>urn:node:KNB</identifier>
<name>KNB Data Repository</name>
<description>The Knowledge Network for Biocomplexity (KNB) is a national ... </description>
<baseURL>https://knb.ecoinformatics.org/knb/d1/mn</baseURL>
<services>
<service name="MNCore" version="v1" available="true"/>
<service name="MNCore" version="v2" available="true"/>
<service name="MNRead" version="v1" available="true"/>
<service name="MNRead" version="v2" available="true"/>
<service name="MNAuthorization" version="v1" available="true"/>
<service name="MNAuthorization" version="v2" available="true"/>
<service name="MNStorage" version="v1" available="true"/>
<service name="MNStorage" version="v2" available="true"/>
<service name="MNReplication" version="v1" available="true"/>
<service name="MNReplication" version="v2" available="true"/>
<service name="MNPackage" version="v1" available="true"/>
<service name="MNPackage" version="v2" available="true"/>
<service name="MNView" version="v2" available="true"/>
</services>
<synchronization>
<schedule hour="*" mday="*" min="0/3" mon="*" sec="10" wday="?" year="*"/>
<lastHarvested>2019-09-14T23:40:15.289+00:00</lastHarvested>
<lastCompleteHarvest>1900-01-01T00:00:00.000+00:00</lastCompleteHarvest>
</synchronization>
<subject>CN=urn:node:KNB,DC=dataone,DC=org</subject>
<contactSubject>CN=Christopher Jones A2108,O=Google,C=US,DC=cilogon,DC=org</contactSubject>
<property key="CN_operational_status">operational</property>
<property key="CN_date_operational">2012-07-23T00:00:0.000Z</property>
<property key="CN_node_name">Knowledge Network for Biocomplexity</property>
<property key="CN_logo_url">https://raw.githubusercontent.com/DataONEorg/member-node-info/master/production/graphics/web/KNB.png</property>
<property key="CN_info_url">https://knb.ecoinformatics.org/</property>
<property key="CN_location_lonlat">-119.697933,34.420222</property>
</node>
<node replicate="false" synchronize="true" type="mn" state="up">
...
</ns3:nodeList>
|
CNCore.
ping
()¶GET /monitor/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.
Version: | 1.0, (2.0) |
---|---|
Use Cases: | |
REST URL: |
|
Returns: | Null body or Exception. The body of the message is ignored by the caller. The HTTP header Date MUST be set in the response. |
Return type: | null |
Raises: |
|
Response
The response should be a valid HTTP response with a blank or arbitrary body. Only the HTTP header information is considered by the requestor. A successful response MUST have a HTTP status code of 200. In case of an error condition, the appropriate HTTP status code MUST be set, and an exception or error information MAY be returned in the response body.
Example
Example of ping request and response for a Member Node (Coordinating Nodes
implement the same functionality). Lines prefixed with “>” and “<” indicate
outgoing and returned information respectively. Lines associated with SSL
connection initiation and close are not shown here. Note that the actual response
headers may vary, the only required header fields are the first status line and a
Date
entry. However in order to fully support clients that may cache the response,
it is recommended that Expires
, and Cache-Control
headers are returned.
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 | curl -v "https://cn.dataone.org/cn/v2/monitor/ping/"
> GET /cn/v2/monitor/ping HTTP/1.1
> Host: cn.dataone.org
> User-Agent: curl/7.65.3
> Accept: */*
>
< HTTP/1.1 200 200
< Date: Tue, 17 Sep 2019 13:13:04 GMT
< Server: Apache/2.4.41 (Ubuntu)
< Vary: User-Agent
< Expires: -1
< Cache-Control: private, max-age=0
< Content-Length: 0
< Access-Control-Allow-Origin:
< Access-Control-Allow-Credentials: true
< Access-Control-Allow-Headers: Authorization, Content-Type, Location, Content-Length, x-annotator-auth-token
< Access-Control-Expose-Headers: Content-Length, Content-Type, Location
< Access-Control-Allow-Methods: POST, GET, OPTIONS, PUT, DELETE
< Content-Type: text/xml;charset=UTF-8
<
|
CNCore.
registerSystemMetadata
(session, pid, sysmeta)¶POST /meta
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 v2_0.Types.SystemMetadata
has changed.
Version: | 1.0, 2.0 |
---|---|
REST URL: |
|
Parameters: |
|
Returns: | The pid that was updated. |
Return type: | |
Raises: |
|
Example
Todo
Example for CNCore.registerSystemMetadata
CNCore.
reserveIdentifier
(session, id)¶POST /reserve
Reserves the identifier that is unique and can not be used by any other sessions. Future calls to MNStorage.create()
and MNStorage.update()
that reference this ID must be made by the same 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 PID or SID.
Version: | 1.0, 2.0 |
---|---|
Use Cases: | |
REST URL: |
|
Parameters: |
|
Returns: | The identifier that was reserved |
Return type: | |
Raises: |
|
Example
Todo
Example for CNCore.reserveIdentifier
CNCore.
setObsoletedBy
(session, pid, obsoletedByPid, serialVersion)¶PUT /obsoletedBy/{pid}
Updates the 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.
Note: This method is private to the CNs and is not available on the public API.
Version: | 1.0, 2.0 |
---|---|
REST URL: |
|
Parameters: |
|
Returns: | True if the operation succeeds, otherwise false. |
Return type: | boolean |
Raises: |
|
Example
Todo
Example for CNCore.setObsoletedBy
CNCore.
updateSystemMetadata
(session, pid, sysmeta)¶PUT /meta
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 v2_0.Types.SystemMetadata
has changed.
Note: the serial version and the replica list in the new system metadata will be ignored.
Version: | 2.0 |
---|---|
REST URL: |
|
Parameters: |
|
Returns: | True if the update was successful. |
Return type: | boolean |
Raises: |
|
Example
Todo
Example for CNCore.updateSystemMetadata
The CNRead API implements methods that enable object retrieval operations on a Coordinating Node. It includes searches of science metadata and system metadata and exposes log records held by CNs.
describe (session, id) |
HEAD /object/{id} This method provides a lighter weight mechanism than CNRead.getSystemMetadata() for a client to determine basic properties of the referenced object. |
get (session, id) |
GET /object/{id} Retrieves the object identified by id from the node. |
getChecksum (session, pid) |
GET /checksum/{pid} Returns the checksum for the specified object as reported in the system metadata. |
getQueryEngineDescription (session, queryEngine) |
GET /query/{queryType} Provides metadata about the query service of the specified queryEngine. |
getSystemMetadata (session, id) |
GET /meta/{id} Returns the system metadata that contains DataONE specific information about the object identified by id. |
listObjects (session[, fromDate, toDate, …]) |
GET /object[?fromDate={fromDate}&toDate={toDate}&identifier={identifier}&formatId={formatId}&nodeId={nodeId}&start={start}&count={count}] Retrieve the list of objects present on the CN that match the calling parameters. |
listQueryEngines (session) |
GET /query Returns a list of query engines, i.e. |
query (session, queryEngine, query) |
GET /query/{queryEngine}/{query} Submit a query against the specified queryEngine and return the response as formatted by the queryEngine. |
resolve (session, id) |
GET /resolve/{id} Returns a list of nodes (MNs or CNs) known to hold copies of the object identified by id. |
search (session, queryType, query) |
GET /search/{queryType}/{query} Search the metadata catalog and return identifiers of metadata records that match the criteria. |
synchronize (session, pid) |
POST /synchronize Indicates to the CN that a new or existing object identified by PID requires synchronization. |
CNRead.
describe
(session, id)¶HEAD /object/{id}
This method provides a lighter weight mechanism than 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 SystemMetadata.formatId
).
The principal indicated by token must have read privileges on the object, otherwise Exceptions.NotAuthorized
is raised.
If the object does not exist on the node servicing the request, then 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 PID or a SID.
Version: | 1.0, 2.0 |
---|---|
Use Cases: | |
REST URL: |
|
Parameters: |
|
Returns: | A set of values providing a basic description of the object. |
Return type: | |
Raises: |
|
Examples
(HEAD) Retrieve information about the object with identifier “ABC123”:
curl -I http://mn1.dataone.org/mn/v1/object/ABC123
HTTP/1.1 200 OK
Last-Modified: Wed, 16 Dec 2009 13:58:34 GMT
Content-Length: 10400
Content-Type: application/octet-stream
DataONE-ObjectFormat: eml://ecoinformatics.org/eml-2.0.1
DataONE-Checksum: SHA-1,2e01e17467891f7c933dbaa00e1459d23db3fe4f
DataONE-SerialVersion: 1234
(HEAD) An error response to a describe() request for object “IDONTEXIST”:
curl -I http://mn1.dataone.org/mn/v1/object/IDONTEXIST
HTTP/1.1 404 Not Found
Last-Modified: Wed, 16 Dec 2009 13:58:34 GMT
Content-Length: 1182
Content-Type: text/xml
DataONE-Exception-Name: NotFound
DataONE-Exception-DetailCode: 1380
DataONE-Exception-Description: The specified object does not exist on this node.
DataONE-Exception-PID: IDONTEXIST
CNRead.
get
(session, id)¶GET /object/{id}
Retrieves the object identified by id from the node. If the object is not present on the node, then an 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 PID or a SID.
Version: | 1.0, 2.0 |
---|---|
Use Cases: | |
REST URL: |
|
Parameters: |
|
Returns: | For science metadata objects, this will be the exact byte stream of the science metadata object as it was original ingested. Note that additional object types may in the future be returned by the get method. |
Return type: | |
Raises: |
|
Example
See MNRead.get()
for additional details and examples.
CNRead.
getChecksum
(session, pid)¶GET /checksum/{pid}
Returns the checksum for the specified object as reported in the system metadata.
Note that the signature of this method differs from MNRead.getChecksum()
as that method takes an optional algorithm parameter.
Version: | 1.0, (2.0) |
---|---|
Use Cases: | |
REST URL: |
|
Parameters: |
|
Returns: | The checksum of the specified object |
Return type: | |
Raises: |
|
Example
Todo
Example for CNRead.getChecksum
CNRead.
getQueryEngineDescription
(session, queryEngine)¶GET /query/{queryType}
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.
Version: | 1.1, (2.0) |
---|---|
REST URL: |
|
Parameters: |
|
Returns: | A list of fields that are supported by the search index and additional metadata. |
Return type: | |
Raises: |
|
Example
Todo
Example for CNRead.getQueryEngineDescription
CNRead.
getSystemMetadata
(session, id)¶GET /meta/{id}
Returns the 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 PID or a SID and the returned v2_0.Types.SystemMetadata
structure has changed.
Version: | 1.0, 2.0 |
---|---|
Use Cases: | |
REST URL: |
|
Parameters: |
|
Returns: | A system metadata document describing the object. |
Return type: | |
Raises: |
|
Example
See MNRead.getSystemMetadata()
for additional details and examples.
CNRead.
listObjects
(session, fromDate=None, toDate=None, formatId=None, identifier=None, start=0, count=1000, nodeId=None)¶GET /object[?fromDate={fromDate}&toDate={toDate}&identifier={identifier}&formatId={formatId}&nodeId={nodeId}&start={start}&count={count}]
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.
Version: | 1.0, (2.0) |
---|---|
Use Cases: | |
REST URL: |
|
Parameters: |
|
Returns: | The list of PIDs that match the query criteria. If none match, an empty list is returned. |
Return type: | |
Raises: |
|
Example
Todo
Example for CNRead.listObjects
CNRead.
listQueryEngines
(session)¶GET /query
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.
Version: | 1.1, (2.0) |
---|---|
REST URL: |
|
Parameters: | session (Types.Session) – Session information that contains the identity of the calling user as retrieved from the X.509 certificate. Transmitted as part of the SSL handshake process. |
Returns: | A list of names of queryEngines available to the user identified by session. |
Return type: | |
Raises: |
|
Example
Todo
Example for CNRead.listQueryEngines
CNRead.
query
(session, queryEngine, query)¶GET /query/{queryEngine}/{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.
Version: | 1.1, (2.0) |
---|---|
Use Cases: | |
REST URL: |
|
Parameters: |
|
Returns: | The structure of the response is determined by the chosen search engine and parameters provided to it. |
Return type: | |
Raises: |
|
Example
Todo
Example for CNRead.query
CNRead.
resolve
(session, id)¶GET /resolve/{id}
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 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 PID or a 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).
Version: | 1.0, 2.0 |
---|---|
Use Cases: | |
REST URL: |
|
Parameters: |
|
Returns: | A list of nodes known to contain copies of the target object, plus the URLs known to resolve to the node get methods. |
Return type: | |
Raises: |
|
Examples
XML (default) in response to Accept: text/xml
:
curl -X GET -H "Accept: text/xml" http://cn.dataone.org/object/resolve/1234
or
curl -X GET -H "Accept: */*" http://cn.dataone.org/object/resolve/1234
<objectLocationList xmlns:d1="http://ns.dataone.org/service/types/v1">
<identifier>1234</identifier>
<objectLocation>
<nodeIdentifier>mn1</nodeIdentifier>
<baseURL>http://mn1.dataone.org/mn</baseURL>
<version>v1</version>
<url>http://mn1.dataone.org/mn/object/1234</url>
</objectLocation>
<objectLocation>
<nodeIdentifier>mn2</nodeIdentifier>
<baseURL>http://mn2.dataone.org/mn</baseURL>
<version>v1</version>
<url>http://mn2.dataone.org/some_base/object/1234</url>
</objectLocation>
<objectLocation>
<nodeIdentifier>cn1</nodeIdentifier>
<baseURL>http://cn1.dataone.org/mn</baseURL>
<version>v1</version>
<url>http://cn1.dataone.org/cn/object/1234</url>
</objectLocation>
<objectLocation>
<nodeIdentifier>cn2</nodeIdentifier>
<baseURL>http://cn2.dataone.org/mn</baseURL>
<version>v1</version>
<url>http://cn2.dataone.org/cn/object/1234</url>
</objectLocation>
<objectLocation>
<nodeIdentifier>cn3</nodeIdentifier>
<baseURL>http://cn3.dataone.org/mn</baseURL>
<version>v1</version>
<url>http://cn3.dataone.org/cn/object/1234</url>
</objectLocation>
</objectLocationList>
CNRead.
search
(session, queryType, query)¶GET /search/{queryType}/{query}
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”
Version: | 1.0, (2.0) |
---|---|
Use Cases: | |
REST URL: |
|
Parameters: |
|
Returns: | A list of objects that match the specified search criteria |
Return type: | |
Raises: |
|
Example
Todo
Example for CNRead.search
CNRead.
synchronize
(session, pid)¶POST /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.
Version: | 2.0 |
---|---|
REST URL: |
|
Parameters: |
|
Returns: | True if the synchronization request was successfully queued, otherwise False |
Return type: | boolean |
Raises: |
|
Example
Todo
Example for CNRead.synchronize
View operations to see formatted versions of metadata and data for CNs.
The CNView API implements methods that enable viewing content on a 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.
listViews (session) |
GET /views Provides a list of usable themes for rendering content in a view, including a required ‘default’ theme. |
view (session, theme, id) |
GET /views/{theme}/{id} Provides a formatted view of an object (science metadata, data, resource, or other) using the given named theme. |
CNView.
listViews
(session)¶GET /views
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.
Version: | 2.0 |
---|---|
REST URL: |
|
Parameters: | session (Types.Session) – Session information that contains the identity of the calling user as retrieved from the X.509 certificate. Transmitted as part of the SSL handshake process. |
Returns: | A list of available themes that can be used with the MNView.view service. |
Return type: | |
Raises: |
|
Example
Todo
Example for CNView.listViews
CNView.
view
(session, theme, id)¶GET /views/{theme}/{id}
Provides a formatted view of an object (science metadata, data, resource, or other) using the given named theme.
The service 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 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.
Version: | 2.0 |
---|---|
REST URL: |
|
Parameters: |
|
Returns: | Any return type is allowed, including application/octet-stream, but the format of the response should be specialized by the requested theme. |
Return type: | |
Raises: |
|
Example
Todo
Example for CNView.view
Methods for authorization and access control.
isAuthorized (session, id, action) |
GET /isAuthorized/{id}?action={action} Test if the user identified by the provided token has authorization for operation on the specified object. |
setAccessPolicy (session, id, accessPolicy, …) |
PUT /accessRules/{id} Sets the access permissions for an object identified by id. |
setRightsHolder (session, id, userId, …) |
PUT /owner/{id} Changes ownership (RightsHolder) of the specified object to the subject specified by userId |
CNAuthorization.
isAuthorized
(session, id, action)¶GET /isAuthorized/{id}?action={action}
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 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 NotAuthorized
exception MUST be raised.
v2.0: The supplied identifier may be a PID or a SID.
Version: | 1.0, 2.0 |
---|---|
Use Cases: | |
REST URL: |
|
Parameters: |
|
Returns: | True if the operation is allowed |
Return type: | boolean |
Raises: |
|
Example
Todo
Example for CNAuthorization.isAuthorized
CNAuthorization.
setAccessPolicy
(session, id, accessPolicy, serialVersion)¶PUT /accessRules/{id}
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 NotAuthorized
.
v2.0: The supplied identifier may be a PID or a SID.
Version: | 1.0, 2.0 |
---|---|
Use Cases: | |
REST URL: |
|
Parameters: |
|
Returns: | True if the operation succeeds, otherwise false. |
Return type: | boolean |
Raises: |
|
Example
Todo
Example for CNAuthorization.setAccessPolicy
CNAuthorization.
setRightsHolder
(session, id, userId, serialVersion)¶PUT /owner/{id}
Changes ownership (RightsHolder) of the specified object to the subject specified by userId
v2.0: The supplied identifier may be a PID or a SID.
Version: | 1.0, 2.0 |
---|---|
Use Cases: | |
REST URL: |
|
Parameters: |
|
Returns: | Identifier of the object that was modified |
Return type: | |
Raises: |
|
Example
Todo
Example for CNAuthorization.setRightsHolder
Methods for account management and identity mapping.
confirmMapIdentity (session, subject) |
PUT /accounts/pendingmap/{subject} Confirms a previously initiated identity mapping. |
createGroup (session, group) |
POST /groups Create a group with the given name. |
denyMapIdentity (session, subject) |
DELETE /accounts/pendingmap/{subject} Denies a previously initiated identity mapping. |
getPendingMapIdentity (session, subject) |
GET /accounts/pendingmap/{subject} Gets the SubjectInfo of a previously initiated identity mapping. |
getSubjectInfo (session, subject) |
GET /accounts/{subject} Get the information about a Person (their equivalent identities, and the Groups to which they belong) or the Group (including members). |
listSubjects (session, query, status, start, …) |
GET /accounts?query={query}[&status={status}&start={start}&count={count}] List the subjects, including users, groups, and systems, that match search criteria. |
mapIdentity (session, primarySubject, …) |
POST /accounts/map Create a new mapping between the two identities, asserting that they represent the same subject. |
registerAccount (session, person) |
POST /accounts Create a new subject in the DataONE system. |
removeMapIdentity (session, subject) |
DELETE /accounts/map/{subject} Removes a previously asserted identity mapping from the Subject in the Session to the Subject given by the parameter. |
requestMapIdentity (session, subject) |
POST /accounts/pendingmap Request a new mapping between the authenticated identity in the session and the given identity, asserting that they represent the same subject. |
updateAccount (session, subject, person) |
PUT /accounts/{subject} Update an existing subject in the DataONE system. |
updateGroup (session, group) |
PUT /groups Add members to the named group. |
verifyAccount (session, subject) |
PUT /accounts/verification/{subject} Verify that the Person data associated with this Subject is a true representation of the real world person. |
CNIdentity.
confirmMapIdentity
(session, subject)¶PUT /accounts/pendingmap/{subject}
Confirms a previously initiated identity mapping. If subject A asserts that B is the same identity through 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.
Version: | 1.0, (2.0) |
---|---|
REST URL: |
|
Parameters: |
|
Returns: | True if the map was successfully created, false otherwise. |
Return type: | boolean |
Raises: |
|
Example
Todo
Example for CNIdentity.confirmMapIdentity
CNIdentity.
createGroup
(session, group)¶POST /groups
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.
Version: | 1.0, (2.0) |
---|---|
REST URL: |
|
Parameters: |
|
Returns: | The Subject of the group that was created. |
Return type: | |
Raises: |
|
Example
Todo
Example for CNIdentity.createGroup
CNIdentity.
denyMapIdentity
(session, subject)¶DELETE /accounts/pendingmap/{subject}
Denies a previously initiated identity mapping. If subject A asserts that B is the same identity through 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.
Version: | 1.0, (2.0) |
---|---|
REST URL: |
|
Parameters: |
|
Returns: | True if the map was successfully created, false otherwise. |
Return type: | boolean |
Raises: |
|
Example
Todo
Example for CNIdentity.denyMapIdentity
CNIdentity.
getPendingMapIdentity
(session, subject)¶GET /accounts/pendingmap/{subject}
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.
Version: | 1.0, (2.0) |
---|---|
REST URL: |
|
Parameters: |
|
Returns: | The SubjectInfo |
Return type: | |
Raises: |
|
Example
Todo
Example for CNIdentity.getPendingMapIdentity
CNIdentity.
getSubjectInfo
(session, subject)¶GET /accounts/{subject}
Get the information about a Person (their equivalent identities, and the Groups to which they belong) or the Group (including members).
Version: | 1.0, (2.0) |
---|---|
Use Cases: | |
REST URL: |
|
Parameters: |
|
Returns: | The Person or Group details are contained in the returned SubjectList for the given Subject |
Return type: | |
Raises: |
|
Example
Todo
Example for CNIdentity.getSubjectInfo
CNIdentity.
listSubjects
(session, query, status, start, count)¶GET /accounts?query={query}[&status={status}&start={start}&count={count}]
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.
Version: | 1.0, (2.0) |
---|---|
REST URL: |
|
Parameters: |
|
Returns: | The list of people and groups that match the query. |
Return type: | |
Raises: |
|
Example
Todo
Example for CNIdentity.listSubjects
CNIdentity.
mapIdentity
(session, primarySubject, secondarySubject)¶POST /accounts/map
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.
Version: | 1.0, (2.0) |
---|---|
REST URL: |
|
Parameters: |
|
Returns: | True if the mapping was successfully initiated, false otherwise. |
Return type: | boolean |
Raises: |
|
Example
Todo
Example for CNIdentity.mapIdentity
CNIdentity.
registerAccount
(session, person)¶POST /accounts
Create a new 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.
Version: | 1.0, (2.0) |
---|---|
Use Cases: | |
REST URL: |
|
Parameters: |
|
Returns: | The new subject in the DataONE system. This may be a simple identifier. |
Return type: | |
Raises: |
|
Example
Todo
Example for CNIdentity.registerAccount
CNIdentity.
removeMapIdentity
(session, subject)¶DELETE /accounts/map/{subject}
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.
Version: | 1.0, (2.0) |
---|---|
REST URL: |
|
Parameters: |
|
Returns: | True if the map was successfully created, false otherwise. |
Return type: | boolean |
Raises: |
|
Example
Todo
Example for CNIdentity.removeMapIdentity
CNIdentity.
requestMapIdentity
(session, subject)¶POST /accounts/pendingmap
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.
Version: | 1.0, (2.0) |
---|---|
REST URL: |
|
Parameters: |
|
Returns: | True if the mapping was successfully initiated, false otherwise. |
Return type: | boolean |
Raises: |
|
Example
Todo
Example for CNIdentity.requestMapIdentity
CNIdentity.
updateAccount
(session, subject, person)¶PUT /accounts/{subject}
Update an existing 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.
Version: | 1.0, (2.0) |
---|---|
Use Cases: | |
REST URL: |
|
Parameters: |
|
Returns: | The Subject in the DataONE system that was updated. |
Return type: | |
Raises: |
|
Example
Todo
Example for CNIdentity.updateAccount
CNIdentity.
updateGroup
(session, group)¶PUT /groups
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.
Version: | 1.0, (2.0) |
---|---|
REST URL: |
|
Parameters: |
|
Returns: | True if the group that was modified successfully, false otherwise |
Return type: | boolean |
Raises: |
|
Example
Todo
Example for CNIdentity.updateGroup
CNIdentity.
verifyAccount
(session, subject)¶PUT /accounts/verification/{subject}
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.
Version: | 1.0, (2.0) |
---|---|
REST URL: |
|
Parameters: |
|
Returns: | True if the account verification succeeds, otherwise false. |
Return type: | boolean |
Raises: |
|
Example
Todo
Example for CNIdentity.verifyAccount
Supports operations for replication of content between Member Nodes.
The Data Replication API operates in conjunction with the
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.
deleteReplicationMetadata (session, pid, …) |
PUT /removeReplicaMetadata/{pid} Removes the replication information for the specified node from the object system metadata identified by pid. |
isNodeAuthorized (session, targetNodeSubject, pid) |
GET /replicaAuthorizations/{pid}?targetNodeSubject={targetNodeSubject} 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. |
setReplicationPolicy (session, id, policy, …) |
PUT /replicaPolicies/{id} Updates the replication policy entry for an object by updating the system metadata. |
setReplicationStatus (session, pid, nodeRef, …) |
PUT /replicaNotifications/{pid} Update the replication status of the system metadata, ensuring that the change is appropriate for the given state of system metadata. |
updateReplicationMetadata (session, pid, …) |
PUT /replicaMetadata/{pid} Replaces the replica with matching nodeRef in the system metadata of the specified object. |
CNReplication.
deleteReplicationMetadata
(session, pid, nodeId, serialVersion)¶PUT /removeReplicaMetadata/{pid}
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.
Version: | 1.0, (2.0) |
---|---|
REST URL: |
|
Parameters: |
|
Returns: | True if the replication metadata was successfully deleted. |
Return type: | boolean |
Raises: |
|
Example
Todo
Example for CNReplication.deleteReplicationMetadata
CNReplication.
isNodeAuthorized
(session, targetNodeSubject, pid)¶GET /replicaAuthorizations/{pid}?targetNodeSubject={targetNodeSubject}
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.
Version: | 1.0, (2.0) |
---|---|
REST URL: |
|
Parameters: |
|
Returns: | True on success |
Return type: | boolean |
Raises: |
|
Example
Todo
Example for CNReplication.isNodeAuthorized
CNReplication.
setReplicationPolicy
(session, id, policy, serialVersion)¶PUT /replicaPolicies/{id}
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 PID or SID.
Version: | 1.0, 2.0 |
---|---|
REST URL: |
|
Parameters: |
|
Returns: | True on success |
Return type: | boolean |
Raises: |
|
Example
Todo
Example for CNReplication.setReplicationPolicy
CNReplication.
setReplicationStatus
(session, pid, nodeRef, status, failure)¶PUT /replicaNotifications/{pid}
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.
Version: | 1.0, (2.0) |
---|---|
Use Cases: | |
REST URL: |
|
Parameters: |
|
Returns: | True if the operation is allowed and expected, otherwise an exception should be raised. |
Return type: | boolean |
Raises: |
|
Example
Todo
Example for CNReplication.setReplicationStatus
CNReplication.
updateReplicationMetadata
(session, pid, replicaMetadata, serialVersion)¶PUT /replicaMetadata/{pid}
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.
Version: | 1.0, (2.0) |
---|---|
REST URL: |
|
Parameters: |
|
Returns: | True on success |
Return type: | boolean |
Raises: |
|
Example
Todo
Example for CNReplication.updateReplicationMetadata
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.
getNodeCapabilities (nodeid) |
GET /node/{nodeid} For retrieving the capabilities of the specified node if it is registered on the Coordinating Node being called. |
register (session, node) |
POST /node Register a new node in the system. |
updateNodeCapabilities (session, nodeid, node) |
PUT /node/{nodeid} For updating the capabilities of the specified node. |
CNRegister.
getNodeCapabilities
(nodeid)¶GET /node/{nodeid}
For retrieving the capabilities of the specified node if it is registered on the Coordinating Node being called.
v2.0: The structure of v2_0.Types.Node
has changed.
Version: | 1.0, 2.0 |
---|---|
REST URL: |
|
Parameters: | nodeid (Types.NodeReference) – The identifier of the existing node entry being looked up. Transmitted as part of the URL path and must be escaped accordingly. |
Returns: | An instance of :class`Types.Node` that contains the Node information. |
Return type: | |
Raises: |
|
Example
Todo
Example for CNRegister.getNodeCapabilities
CNRegister.
register
(session, node)¶POST /node
Register a new node in the system. If the node already exists, then a IdentifierNotUnique
exception MUST be returned.
v2.0: The structure of v2_0.Types.Node
has changed.
Version: | 1.0, 2.0 |
---|---|
REST URL: |
|
Parameters: |
|
Returns: | The identifier of the new node entry if successful, otherwise an error is raised. |
Return type: | |
Raises: |
|
Example
Todo
Example for CNRegister.register
CNRegister.
updateNodeCapabilities
(session, nodeid, node)¶PUT /node/{nodeid}
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 v2_0.Types.Node
has changed.
Version: | 1.0, 2.0 |
---|---|
REST URL: |
|
Parameters: |
|
Returns: | True if operation is successful |
Return type: | boolean |
Raises: |
|
Example
Todo
Example for CNRegister.updateNodeCapabilities