Navigation

Coordinating Node APIs

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

Methods for CN component
Tier REST Function Parameters
Tier 1 GET /monitor/ping CNCore.ping() () -> null
Tier 1 POST /object CNCore.create() (session, pid, object, sysmeta) -> Types.Identifier
Tier 1 GET /formats CNCore.listFormats() () -> Types.ObjectFormatList
Tier 1 GET /formats/{formatId} CNCore.getFormat() (formatId) -> Types.ObjectFormat
Tier 1 GET /log?[fromDate={fromDate}][&toDate={toDate}][&event={event}][&pidFilter={pidFilter}][&start={start}][&count={count}] CNCore.getLogRecords() (session, [fromDate], [toDate], [event], [pidFilter], [start], [count]) -> Types.Log
Tier 1 POST /reserve CNCore.reserveIdentifier() (session, pid) -> Types.Identifier
Tier 1 POST /generate CNCore.generateIdentifier() (session, scheme, [fragment]) -> Types.Identifier
Tier 1 GET /checksum CNCore.listChecksumAlgorithms() () -> Types.ChecksumAlgorithmList
  PUT /obsoletedBy/{pid} CNCore.setObsoletedBy() (session, pid, obsoletedByPid, serialVersion) -> boolean
Tier 3 DELETE /object/{pid} CNCore.delete() (session, pid) -> Types.Identifier
Tier 3 PUT /archive/{pid} CNCore.archive() (session, pid) -> Types.Identifier
Tier 1 GET /node CNCore.listNodes() () -> Types.NodeList
Tier 1 POST /meta CNCore.registerSystemMetadata() (session, pid, sysmeta) -> Types.Identifier
  GET /reserve/{pid}?subject={subject} CNCore.hasReservation() (session, subject, pid) -> boolean
Tier 1 GET /object/{pid} CNRead.get() (session, pid) -> Types.OctetStream
Tier 1 GET /meta/{pid} CNRead.getSystemMetadata() (session, pid) -> Types.SystemMetadata
Tier 1 HEAD /object/{pid} CNRead.describe() (session, pid) -> Types.DescribeResponse
Tier 1 GET /resolve/{pid} CNRead.resolve() (session, pid) -> Types.ObjectLocationList
Tier 1 GET /checksum/{pid} CNRead.getChecksum() (session, pid) -> Types.Checksum
Tier 1 GET /object[?fromDate={fromDate}&toDate={toDate}&formatId= {formatId}&replicaStatus={replicaStatus}&start={start}&count={count}] CNRead.listObjects() (session, [fromDate], [toDate], [formatId], [replicaStatus], [start=0], [count=1000]) -> Types.ObjectList
Tier 1 GET /search/{queryType}/{query} CNRead.search() (session, queryType, query) -> Types.ObjectList
Tier 1 GET /query/{queryEngine}/{query} CNRead.query() (session, queryEngine, query) -> Types.OctetStream
Tier 1 GET /query/{queryType} CNRead.getQueryEngineDescription() (session, queryEngine) -> Types.QueryEngineDescription
Tier 1 GET /query CNRead.listQueryEngines() (session) -> Types.QueryEngineList
Tier 2 PUT /owner/{pid} CNAuthorization.setRightsHolder() (session, pid, userId, serialVersion) -> Types.Identifier
Tier 2 GET /isAuthorized/{pid}?action={action} CNAuthorization.isAuthorized() (session, pid, action) -> boolean
Tier 2 PUT /accessRules/{pid} CNAuthorization.setAccessPolicy() (session, pid, accessPolicy, serialVersion) -> boolean
Tier 2 POST /accounts CNIdentity.registerAccount() (session, person) -> Types.Subject
Tier 2 PUT /accounts/{subject} CNIdentity.updateAccount() (session, subject, person) -> Types.Subject
Tier 2 PUT /accounts/verification/{subject} CNIdentity.verifyAccount() (session, subject) -> boolean
Tier 2 GET /accounts/{subject} CNIdentity.getSubjectInfo() (session, subject) -> Types.SubjectInfo
Tier 2 GET /accounts?query={query}[&status={status}&start={start}&count={count}] CNIdentity.listSubjects() (session, query, status, start, count) -> Types.SubjectInfo
Tier 2 POST /accounts/map CNIdentity.mapIdentity() (session, primarySubject, secondarySubject) -> boolean
Tier 2 DELETE /accounts/map/{subject} CNIdentity.removeMapIdentity() (session, subject) -> boolean
Tier 2 POST /accounts/pendingmap CNIdentity.requestMapIdentity() (session, subject) -> boolean
Tier 2 PUT /accounts/pendingmap/{subject} CNIdentity.confirmMapIdentity() (session, subject) -> boolean
Tier 2 GET /accounts/pendingmap/{subject} CNIdentity.getPendingMapIdentity() (session, subject) -> Types.SubjectInfo
Tier 2 DELETE /accounts/pendingmap/{subject} CNIdentity.denyMapIdentity() (session, subject) -> boolean
Tier 2 POST /groups CNIdentity.createGroup() (session, group) -> Types.Subject
Tier 2 PUT /groups CNIdentity.updateGroup() (session, group) -> boolean
Tier 4 PUT /replicaNotifications/{pid} CNReplication.setReplicationStatus() (session, pid, nodeRef, status, failure) -> boolean
Tier 4 PUT /replicaMetadata/{pid} CNReplication.updateReplicationMetadata() (session, pid, replicaMetadata, serialVersion) -> boolean
Tier 4 PUT /replicaPolicies/{pid} CNReplication.setReplicationPolicy() (session, pid, policy, serialVersion) -> boolean
Tier 4 GET /replicaAuthorizations/{pid}?targetNodeSubject={targetNodeSubject} CNReplication.isNodeAuthorized() (session, targetNodeSubject, pid) -> boolean
  PUT /removeReplicaMetadata/{pid} CNReplication.deleteReplicationMetadata() (session, pid, nodeId, serialVersion) -> boolean
Tier 2 PUT /node/{nodeid} CNRegister.updateNodeCapabilities() (session, nodeid, node) -> boolean
Tier 2 POST /node CNRegister.register() (session, node) -> Types.NodeReference

Core API

Functions defined in CNCore
Tier REST Function Parameters
Tier 1 GET /monitor/ping ping() () -> null
Tier 1 POST /object create() (session, pid, object, sysmeta) -> Types.Identifier
Tier 1 GET /formats listFormats() () -> Types.ObjectFormatList
Tier 1 GET /formats/{formatId} getFormat() (formatId) -> Types.ObjectFormat
Tier 1 GET /log?[fromDate={fromDate}][&toDate={toDate}][&event={event}][&pidFilter={pidFilter}][&start={start}][&count={count}] getLogRecords() (session, [fromDate], [toDate], [event], [pidFilter], [start], [count]) -> Types.Log
Tier 1 POST /reserve reserveIdentifier() (session, pid) -> Types.Identifier
Tier 1 POST /generate generateIdentifier() (session, scheme, [fragment]) -> Types.Identifier
Tier 1 GET /checksum listChecksumAlgorithms() () -> Types.ChecksumAlgorithmList
  PUT /obsoletedBy/{pid} setObsoletedBy() (session, pid, obsoletedByPid, serialVersion) -> boolean
Tier 3 DELETE /object/{pid} delete() (session, pid) -> Types.Identifier
Tier 3 PUT /archive/{pid} archive() (session, pid) -> Types.Identifier
Tier 1 GET /node listNodes() () -> Types.NodeList
Tier 1 POST /meta registerSystemMetadata() (session, pid, sysmeta) -> Types.Identifier
  GET /reserve/{pid}?subject={subject} hasReservation() (session, subject, pid) -> boolean
CNCore.ping() → null

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.

Use Cases:

UC10
Rest URL:

GET /monitor/ping
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.

Example

Example of ping request and response for a Member Node. Lines prefixed with “>” indicate outgoing information, lines prefixed with “<” show content returned from the server. 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 the Expires, and Cache-Control headers are returned.

export NODE="https://demo2.test.dataone.org/knb/d1/mn"
curl -k -v "$NODE/v1/monitor/ping"

> GET /knb/d1/mn/v1/monitor/ping HTTP/1.1
> User-Agent: curl/7.21.6 (x86_64-pc-linux-gnu) libcurl/7.21.6 OpenSSL/1.0.0e zlib/1.2.3.4 libidn/1.22 librtmp/2.3
> Host: demo2.test.dataone.org
> Accept: */*
>
< HTTP/1.1 200 OK
< Date: Tue, 06 Mar 2012 14:19:59 GMT
< Server: Apache/2.2.14 (Ubuntu)
< Content-Length: 0
< Content-Type: text/plain
<
CNCore.create(session, pid, object, sysmeta) → Identifier

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.

Use Cases:

UC04, UC09, UC16
Rest URL:

POST /object
Parameters:
  • session (Types.Session) – Session information that contains the identity of the calling user as retrieved from the X.509 certificate which must be traceable to the CILogon service. The subject of the session defaults to the public user if the certificate was not provided with the request. Transmitted as part of the SSL handshake process.
  • pid (Types.Identifier) – The identifier that should be used in DataONE to identify and access the object. This is an Unicode string that follows the constraints on identifiers described in Identifiers in DataONE. Transmitted as a UTF-8 String as a Param part of the MIME multipart/mixed message.
  • object (bytes) – The object (i.e. Science Metadata) bytes. Transmitted as an UTF-8 encoded XML structure for the respective type as defined in the DataONE types schema, as a File part of the MIME multipart/mixed message.
  • sysmeta (Types.SystemMetadata) – The complete system metadata document describing the object. Transmitted as an UTF-8 encoded XML structure for the respective type as defined in the DataONE types schema, as a File part of the MIME multipart/mixed message.
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:

Types.Identifier
Raises:
CNCore.listFormats() → ObjectFormatList

Returns a list of all object formats registered in the DataONE Object Format Vocabulary.

Rest URL:

GET /formats
Returns:

The list of object formats registered in the DataONE Object Format Vocabulary
Return type:

Types.ObjectFormatList
Raises:

Example

curl "http://cn.dataone.org/cn/v1/formats"
<?xml version="1.0" encoding="UTF-8"?>
<?xml-stylesheet type="text/xsl" href="/cn/xslt/dataone.types.v1.xsl"?>
<d1:objectFormatList xmlns:d1="http://ns.dataone.org/service/types/v1" count="67" start="0" total="67">
  <objectFormat>
    <formatId>-//ecoinformatics.org//eml-access-2.0.0beta4//EN</formatId>
    <formatName>Ecological Metadata Language, Access module, version 2.0.0beta4</formatName>
    <formatType>METADATA</formatType>
  </objectFormat>
  <objectFormat>
    <formatId>-//ecoinformatics.org//eml-attribute-2.0.0beta4//EN</formatId>
    <formatName>Ecological Metadata Language, Attribute module, version 2.0.0beta4</formatName>
    <formatType>METADATA</formatType>
  </objectFormat>
  <objectFormat>
    <formatId>-//ecoinformatics.org//eml-constraint-2.0.0beta4//EN</formatId>
    <formatName>Ecological Metadata Language, Constraint module, version 2.0.0beta4</formatName>
    <formatType>METADATA</formatType>
  </objectFormat>
  ...
</d1:objectFormatList>
CNCore.getFormat(formatId) → ObjectFormat

Returns the object format registered in the DataONE Object Format Vocabulary for the given format identifier.

Rest URL:

GET /formats/{formatId}
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:

Types.ObjectFormat
Raises:

Example

Note

The xml command is implemented by XMLStarlet, and is used here to format the output for easier reading.

$ curl -s "http://cn-dev.dataone.org/cn/v1/formats" | xml fo

<?xml version="1.0" encoding="UTF-8"?>
<?xml-stylesheet type="text/xsl" href="/cn/xslt/dataone.types.v1.xsl"?>
<d1:objectFormatList xmlns:d1="http://ns.dataone.org/service/types/v1" count="67" start="0" total="67">
  <objectFormat>
    <formatId>-//ecoinformatics.org//eml-access-2.0.0beta4//EN</formatId>
    <formatName>Ecological Metadata Language, Access module, version 2.0.0beta4</formatName>
    <formatType>METADATA</formatType>
  </objectFormat>
  <objectFormat>
    <formatId>-//ecoinformatics.org//eml-attribute-2.0.0beta4//EN</formatId>
    <formatName>Ecological Metadata Language, Attribute module, version 2.0.0beta4</formatName>
    <formatType>METADATA</formatType>
  </objectFormat>
  <objectFormat>
    <formatId>-//ecoinformatics.org//eml-constraint-2.0.0beta4//EN</formatId>
    <formatName>Ecological Metadata Language, Constraint module, version 2.0.0beta4</formatName>
    <formatType>METADATA</formatType>
  </objectFormat>
  <objectFormat>
    <formatId>-//ecoinformatics.org//eml-coverage-2.0.0beta4//EN</formatId>
    <formatName>Ecological Metadata Language, Coverage module, version 2.0.0beta4</formatName>
    <formatType>METADATA</formatType>
  </objectFormat>
  <objectFormat>
    <formatId>-//ecoinformatics.org//eml-dataset-2.0.0beta4//EN</formatId>
    <formatName>Ecological Metadata Language, Dataset module, version 2.0.0beta4</formatName>
    <formatType>METADATA</formatType>
  </objectFormat>
  <objectFormat>
    <formatId>-//ecoinformatics.org//eml-distribution-2.0.0beta4//EN</formatId>
    <formatName>Ecological Metadata Language, Distribution module, version 2.0.0beta4</formatName>
    <formatType>METADATA</formatType>
  </objectFormat>
  <objectFormat>
    <formatId>-//ecoinformatics.org//eml-entity-2.0.0beta4//EN</formatId>
    <formatName>Ecological Metadata Language, Entity module, version 2.0.0beta4</formatName>
    <formatType>METADATA</formatType>
  </objectFormat>
  <objectFormat>
    <formatId>-//ecoinformatics.org//eml-literature-2.0.0beta4//EN</formatId>
    <formatName>Ecological Metadata Language, Literature module, version 2.0.0beta4</formatName>
    <formatType>METADATA</formatType>
  </objectFormat>
  <objectFormat>
    <formatId>-//ecoinformatics.org//eml-party-2.0.0beta4//EN</formatId>
    <formatName>Ecological Metadata Language, Party module, version 2.0.0beta4</formatName>
    <formatType>METADATA</formatType>
  </objectFormat>
  <objectFormat>
    <formatId>-//ecoinformatics.org//eml-physical-2.0.0beta4//EN</formatId>
    <formatName>Ecological Metadata Language, Physical module, version 2.0.0beta4</formatName>
    <formatType>METADATA</formatType>
  </objectFormat>
  <objectFormat>
    <formatId>-//ecoinformatics.org//eml-project-2.0.0beta4//EN</formatId>
    <formatName>Ecological Metadata Language, Project module, version 2.0.0beta4</formatName>
    <formatType>METADATA</formatType>
  </objectFormat>
  <objectFormat>
    <formatId>-//ecoinformatics.org//eml-protocol-2.0.0beta4//EN</formatId>
    <formatName>Ecological Metadata Language, Protocol module, version 2.0.0beta4</formatName>
    <formatType>METADATA</formatType>
  </objectFormat>
  <objectFormat>
    <formatId>-//ecoinformatics.org//eml-resource-2.0.0beta4//EN</formatId>
    <formatName>Ecological Metadata Language, Resource module, version 2.0.0beta4</formatName>
    <formatType>METADATA</formatType>
  </objectFormat>
  <objectFormat>
    <formatId>-//ecoinformatics.org//eml-software-2.0.0beta4//EN</formatId>
    <formatName>Ecological Metadata Language, Software module, version 2.0.0beta4</formatName>
    <formatType>METADATA</formatType>
  </objectFormat>
  <objectFormat>
    <formatId>-//ecoinformatics.org//eml-access-2.0.0beta6//EN</formatId>
    <formatName>Ecological Metadata Language, Access module, version 2.0.0beta6</formatName>
    <formatType>METADATA</formatType>
  </objectFormat>
  <objectFormat>
    <formatId>-//ecoinformatics.org//eml-attribute-2.0.0beta6//EN</formatId>
    <formatName>Ecological Metadata Language, Attribute module, version 2.0.0beta6</formatName>
    <formatType>METADATA</formatType>
  </objectFormat>
  <objectFormat>
    <formatId>-//ecoinformatics.org//eml-constraint-2.0.0beta6//EN</formatId>
    <formatName>Ecological Metadata Language, Constraint module, version 2.0.0beta6</formatName>
    <formatType>METADATA</formatType>
  </objectFormat>
  <objectFormat>
    <formatId>-//ecoinformatics.org//eml-coverage-2.0.0beta6//EN</formatId>
    <formatName>Ecological Metadata Language, Coverage module, version 2.0.0beta6</formatName>
    <formatType>METADATA</formatType>
  </objectFormat>
  <objectFormat>
    <formatId>-//ecoinformatics.org//eml-dataset-2.0.0beta6//EN</formatId>
    <formatName>Ecological Metadata Language, Dataset module, version 2.0.0beta6</formatName>
    <formatType>METADATA</formatType>
  </objectFormat>
  <objectFormat>
    <formatId>-//ecoinformatics.org//eml-distribution-2.0.0beta6//EN</formatId>
    <formatName>Ecological Metadata Language, Distribution module, version 2.0.0beta6</formatName>
    <formatType>METADATA</formatType>
  </objectFormat>
  <objectFormat>
    <formatId>-//ecoinformatics.org//eml-entity-2.0.0beta6//EN</formatId>
    <formatName>Ecological Metadata Language, Entity module, version 2.0.0beta6</formatName>
    <formatType>METADATA</formatType>
  </objectFormat>
  <objectFormat>
    <formatId>-//ecoinformatics.org//eml-literature-2.0.0beta6//EN</formatId>
    <formatName>Ecological Metadata Language, Literature module, version 2.0.0beta6</formatName>
    <formatType>METADATA</formatType>
  </objectFormat>
  <objectFormat>
    <formatId>-//ecoinformatics.org//eml-party-2.0.0beta6//EN</formatId>
    <formatName>Ecological Metadata Language, Party module, version 2.0.0beta6</formatName>
    <formatType>METADATA</formatType>
  </objectFormat>
  <objectFormat>
    <formatId>-//ecoinformatics.org//eml-physical-2.0.0beta6//EN</formatId>
    <formatName>Ecological Metadata Language, Physical module, version 2.0.0beta6</formatName>
    <formatType>METADATA</formatType>
  </objectFormat>
  <objectFormat>
    <formatId>-//ecoinformatics.org//eml-project-2.0.0beta6//EN</formatId>
    <formatName>Ecological Metadata Language, Project module, version 2.0.0beta6</formatName>
    <formatType>METADATA</formatType>
  </objectFormat>
  <objectFormat>
    <formatId>-//ecoinformatics.org//eml-protocol-2.0.0beta6//EN</formatId>
    <formatName>Ecological Metadata Language, Protocol module, version 2.0.0beta6</formatName>
    <formatType>METADATA</formatType>
  </objectFormat>
  <objectFormat>
    <formatId>-//ecoinformatics.org//eml-resource-2.0.0beta6//EN</formatId>
    <formatName>Ecological Metadata Language, Resource module, version 2.0.0beta6</formatName>
    <formatType>METADATA</formatType>
  </objectFormat>
  <objectFormat>
    <formatId>-//ecoinformatics.org//eml-software-2.0.0beta6//EN</formatId>
    <formatName>Ecological Metadata Language, Software module, version 2.0.0beta6</formatName>
    <formatType>METADATA</formatType>
  </objectFormat>
  <objectFormat>
    <formatId>eml://ecoinformatics.org/eml-2.0.0</formatId>
    <formatName>Ecological Metadata Language, version 2.0.0</formatName>
    <formatType>METADATA</formatType>
  </objectFormat>
  <objectFormat>
    <formatId>eml://ecoinformatics.org/eml-2.0.1</formatId>
    <formatName>Ecological Metadata Language, version 2.0.1</formatName>
    <formatType>METADATA</formatType>
  </objectFormat>
  <objectFormat>
    <formatId>eml://ecoinformatics.org/eml-2.1.0</formatId>
    <formatName>Ecological Metadata Language, version 2.1.0</formatName>
    <formatType>METADATA</formatType>
  </objectFormat>
  <objectFormat>
    <formatId>eml://ecoinformatics.org/eml-2.1.1</formatId>
    <formatName>Ecological Metadata Language, version 2.1.1</formatName>
    <formatType>METADATA</formatType>
  </objectFormat>
  <objectFormat>
    <formatId>FGDC-STD-001.1-1999</formatId>
    <formatName>
      Content Standard for Digital Geospatial Metadata,
      Biological Data Profile, version 001.1-1999
    </formatName>
    <formatType>METADATA</formatType>
  </objectFormat>
  <objectFormat>
    <formatId>FGDC-STD-001.2-1999</formatId>
    <formatName>
      Content Standard for Digital Geospatial Metadata,
      Metadata Profile for Shoreline Data, version 001.2-1999
    </formatName>
    <formatType>METADATA</formatType>
  </objectFormat>
  <objectFormat>
    <formatId>FGDC-STD-001-1998</formatId>
    <formatName>
      Content Standard for Digital Geospatial Metadata, version 001-1998
    </formatName>
    <formatType>METADATA</formatType>
  </objectFormat>
  <objectFormat>
    <formatId>INCITS 453-2009</formatId>
    <formatName>
      North American Profile of ISO 19115: 2003 Geographic Information - Metadata
    </formatName>
    <formatType>METADATA</formatType>
  </objectFormat>
  <objectFormat>
    <formatId>http://www.unidata.ucar.edu/namespaces/netcdf/ncml-2.2</formatId>
    <formatName>NetCDF Markup Language, version 2.2</formatName>
    <formatType>METADATA</formatType>
  </objectFormat>
  <objectFormat>
    <formatId>CF-1.0</formatId>
    <formatName>
      NetCDF Climate and Forecast Metadata Convention, version 1.0
    </formatName>
    <formatType>DATA</formatType>
  </objectFormat>
  <objectFormat>
    <formatId>CF-1.1</formatId>
    <formatName>
      NetCDF Climate and Forecast Metadata Convention, version 1.1
    </formatName>
    <formatType>DATA</formatType>
  </objectFormat>
  <objectFormat>
    <formatId>CF-1.2</formatId>
    <formatName>
      NetCDF Climate and Forecast Metadata Convention, version 1.2
    </formatName>
    <formatType>DATA</formatType>
  </objectFormat>
  <objectFormat>
    <formatId>CF-1.3</formatId>
    <formatName>
      NetCDF Climate and Forecast Metadata Convention, version 1.3
    </formatName>
    <formatType>DATA</formatType>
  </objectFormat>
  <objectFormat>
    <formatId>CF-1.4</formatId>
    <formatName>
      NetCDF Climate and Forecast Metadata Convention, version 1.4
    </formatName>
    <formatType>DATA</formatType>
  </objectFormat>
  <objectFormat>
    <formatId>http://www.cuahsi.org/waterML/1.0/</formatId>
    <formatName>
      Water Markup Language, version 1.0
    </formatName>
    <formatType>METADATA</formatType>
  </objectFormat>
  <objectFormat>
    <formatId>http://www.cuahsi.org/waterML/1.1/</formatId>
    <formatName>
      Water Markup Language, version 1.0
    </formatName>
    <formatType>METADATA</formatType>
  </objectFormat>
  <objectFormat>
    <formatId>http://www.loc.gov/METS/</formatId>
    <formatName>
      Metadata Encoding and Transmission Standard, version 1
    </formatName>
    <formatType>METADATA</formatType>
  </objectFormat>
  <objectFormat>
    <formatId>netCDF-3</formatId>
    <formatName>Network Common Data Format, version 3</formatName>
    <formatType>METADATA</formatType>
  </objectFormat>
  <objectFormat>
    <formatId>netCDF-4</formatId>
    <formatName>Network Common Data Format, version 4</formatName>
    <formatType>METADATA</formatType>
  </objectFormat>
  <objectFormat>
    <formatId>text/plain</formatId>
    <formatName>Plain Text</formatName>
    <formatType>DATA</formatType>
  </objectFormat>
  <objectFormat>
    <formatId>text/csv</formatId>
    <formatName>Comma Separated Values Text</formatName>
    <formatType>DATA</formatType>
  </objectFormat>
  <objectFormat>
    <formatId>image/bmp</formatId>
    <formatName>Bitmap Image File</formatName>
    <formatType>DATA</formatType>
  </objectFormat>
  <objectFormat>
    <formatId>image/gif</formatId>
    <formatName>Graphics Interchange Format</formatName>
    <formatType>DATA</formatType>
  </objectFormat>
  <objectFormat>
    <formatId>image/jp2</formatId>
    <formatName>JPEG 2000</formatName>
    <formatType>DATA</formatType>
  </objectFormat>
  <objectFormat>
    <formatId>image/jpeg</formatId>
    <formatName>JPEG</formatName>
    <formatType>DATA</formatType>
  </objectFormat>
  <objectFormat>
    <formatId>image/png</formatId>
    <formatName>Portable Network Graphics</formatName>
    <formatType>DATA</formatType>
  </objectFormat>
  <objectFormat>
    <formatId>image/svg+xml</formatId>
    <formatName>Scalable Vector Graphics</formatName>
    <formatType>DATA</formatType>
  </objectFormat>
  <objectFormat>
    <formatId>image/tiff</formatId>
    <formatName>Tagged Image File Format</formatName>
    <formatType>DATA</formatType>
  </objectFormat>
  <objectFormat>
    <formatId>http://rs.tdwg.org/dwc/xsd/simpledarwincore/</formatId>
    <formatName>Simple Darwin Core</formatName>
    <formatType>METADATA</formatType>
  </objectFormat>
  <objectFormat>
    <formatId>http://digir.net/schema/conceptual/darwin/2003/1.0/darwin2.xsd</formatId>
    <formatName>Darwin Core, version 2.0</formatName>
    <formatType>METADATA</formatType>
  </objectFormat>
  <objectFormat>
    <formatId>application/octet-stream</formatId>
    <formatName>Octet Stream</formatName>
    <formatType>DATA</formatType>
  </objectFormat>
  <objectFormat>
    <formatId>http://www.w3.org/2005/Atom</formatId>
    <formatName>ATOM-1.0</formatName>
    <formatType>RESOURCE</formatType>
  </objectFormat>
  <objectFormat>
    <formatId>text/n3</formatId>
    <formatName>N3</formatName>
    <formatType>RESOURCE</formatType>
  </objectFormat>
  <objectFormat>
    <formatId>text/turtle</formatId>
    <formatName>TURTLE</formatName>
    <formatType>RESOURCE</formatType>
  </objectFormat>
  <objectFormat>
    <formatId>http://www.w3.org/TR/rdf-testcases/#ntriples</formatId>
    <formatName>N-TRIPLE</formatName>
    <formatType>RESOURCE</formatType>
  </objectFormat>
  <objectFormat>
    <formatId>http://www.w3.org/TR/rdf-syntax-grammar</formatId>
    <formatName>RDF/XML</formatName>
    <formatType>RESOURCE</formatType>
  </objectFormat>
  <objectFormat>
    <formatId>http://www.w3.org/TR/rdfa-syntax</formatId>
    <formatName>RDFa</formatName>
    <formatType>RESOURCE</formatType>
  </objectFormat>
  <objectFormat>
    <formatId>http://www.openarchives.org/ore/terms</formatId>
    <formatName>Object Reuse and Exchange Vocabulary</formatName>
    <formatType>RESOURCE</formatType>
  </objectFormat>
  <objectFormat>
    <formatId>application/pdf</formatId>
    <formatName>Portable Document Format</formatName>
    <formatType>DATA</formatType>
  </objectFormat>
  <objectFormat>
    <formatId>http://dublincore.org/schemas/xmls/qdc/2008/02/11/simpledc.xsd</formatId>
    <formatName>Simple DC container XML Schema Created 2008-02-11</formatName>
    <formatType>METADATA</formatType>
  </objectFormat>
  <objectFormat>
    <formatId>http://dublincore.org/schemas/xmls/qdc/2008/02/11/qualifieddc.xsd</formatId>
    <formatName>Qualified DC container XML Schema Created 2008-02-11</formatName>
    <formatType>METADATA</formatType>
  </objectFormat>
</d1:objectFormatList>
CNCore.getLogRecords(session[, fromDate][, toDate][, event][, pidFilter][, start][, count]) → Log

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.

Use Cases:

UC16
Rest URL:

GET /log?[fromDate={fromDate}][&toDate={toDate}][&event={event}][&pidFilter={pidFilter}][&start={start}][&count={count}]
Parameters:
  • session (Types.Session) – Session information that contains the identity of the calling user as retrieved from the X.509 certificate which must be traceable to the CILogon service. The subject of the session defaults to the public user if the certificate was not provided with the request. Transmitted as part of the SSL handshake process.
  • fromDate (Types.DateTime) – Starting time for records in response, entries with timestamp greater than or equal to (>=) this value will be returned. Defaults to include all records. Transmitted as a URL query parameter, and so must be escaped accordingly.
  • toDate (Types.DateTime) – End time for records in response, entries with timestamp less than (<) this value will be returned. If not specified, then defaults to now. Transmitted as a URL query parameter, and so must be escaped accordingly.
  • event (Types.Event) – Return only log records for the specified type of event. Default is all. Transmitted as a URL query parameter, and so must be escaped accordingly.
  • pidFilter (string) – Return only log records for identifiers that start with the supplied identifier string. Support for this parameter is optional and MAY be ignored by the Coordinating Node implementation with no warning. Transmitted as a URL query parameter, and so must be escaped accordingly.
  • start (integer) – The zero based index of the first log record to return. Default is 0. Transmitted as a URL query parameter, and so must be escaped accordingly.
  • count (integer) – The maximum number of log records that should be returned in the response. The Member Node may return fewer and the caller should check the total in the response to determine if further pages may be retrieved. Transmitted as a URL query parameter, and so must be escaped accordingly.
Returns:
Return type:

Types.Log
Raises:
CNCore.reserveIdentifier(session, pid) → Identifier

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 pid as key, and the identifier string as value.

Use Cases:

UC16
Rest URL:

POST /reserve
Parameters:
  • session (Types.Session) – Session information that contains the identity of the calling user as retrieved from the X.509 certificate which must be traceable to the CILogon service. The subject of the session defaults to the public user if the certificate was not provided with the request. Transmitted as part of the SSL handshake process.
  • pid (Types.Identifier) – The identifier that is to be reserved. Transmitted as a UTF-8 String as a Param part of the MIME multipart/mixed message.
Returns:

The identifier that was reserved
Return type:

Types.Identifier
Raises:
CNCore.generateIdentifier(session, scheme[, fragment]) → Identifier

Given a scheme and optional fragment, generates an identifier with that scheme and fragment that is unique.

The message body is encoded as MIME Multipart/form-data

Use Cases:

UC16
Rest URL:

POST /generate
Parameters:
  • session (Types.Session) – Session information that contains the identity of the calling user as retrieved from the X.509 certificate which must be traceable to the CILogon service. The subject of the session defaults to the public user if the certificate was not provided with the request. Transmitted as part of the SSL handshake process.
  • scheme (string) – The name of the identifier scheme to be used, drawn from a DataONE-specific vocabulary of identifier scheme names, including several common syntaxes such as DOI, ARK, LSID, UUID, and LSRN, among others. The first version of this method only supports the UUID scheme, and ignores the fragment parameter. Transmitted as a UTF-8 String as a Param part of the MIME multipart/mixed message.
  • fragment (string) – The optional fragment to include in the generated Identifier. This parameter is optional and may not be present in the message body. Transmitted as a UTF-8 String as a Param part of the MIME multipart/mixed message.
Returns:

The identifier that was generated
Return type:

Types.Identifier
Raises:

Todo

Need to provide a list of recommended identifier schemes.

CNCore.listChecksumAlgorithms() → ChecksumAlgorithmList

Returns a list of checksum algorithms that are supported by DataONE.

Rest URL:

GET /checksum
Returns:

A list of supported checksum algorithms.
Return type:

Types.ChecksumAlgorithmList
Raises:
  • Exceptions.NotImplemented –

    (errorCode=501, detailCode=4880)

    The service is not implemented.

  • Exceptions.ServiceFailure –

    (errorCode=500, detailCode=4881)

    A problem occurred with the service that prevented it from returning the expected response.
CNCore.setObsoletedBy(session, pid, obsoletedByPid, serialVersion) → boolean

Updates the Types.SystemMetadata.obsoletedBy property for an object, indicating that the object specified by pid has been obsoleted by the identifier in obsoletedByPid.

Rest URL:

PUT /obsoletedBy/{pid}
Parameters:
  • session (Types.Session) – Session information that contains the identity of the calling user as retrieved from the X.509 certificate which must be traceable to the CILogon service. The Subject of the session MUST have write permission on the object. Transmitted as part of the SSL handshake process.
  • pid (Types.Identifier) – Identifier of the object system metadata being updated. Transmitted as part of the URL path and must be escaped accordingly.
  • obsoletedByPid (Types.Identifier) – Identifier of the object that obsoletes the object identified by pid. Transmitted as a UTF-8 String as a Param part of the MIME multipart/mixed message.
  • serialVersion (unsigned long) – The serial version of the system metadata being updated. If the specified serialVersion does not match the current version at the Coordinating Nodes, then a Exceptions.VersionMismatch error is raised and no changes are made. Transmitted as a UTF-8 String as a Param part of the MIME multipart/mixed message.
Returns:

True if the operation succeeds, otherwise false.
Return type:

boolean
Raises:
  • Exceptions.NotImplemented –

    (errorCode=501, detailCode=4940)

    The service endpoint has not yet been fully implemented

  • Exceptions.ServiceFailure –

    (errorCode=500, detailCode=4941)

    A problem occurred with the service that prevented it from returning the expected response.

  • Exceptions.InvalidRequest –

    (errorCode=400, detailCode=4942)

    The request was malformed and could not be processed.

  • Exceptions.InvalidToken –

    (errorCode=401, detailCode=4943)

    The supplied session information could not be verified as a valid DataONE session.

  • Exceptions.NotFound –

    (errorCode=404, detailCode=4944)

    The specified pid does not exist.

  • Exceptions.NotAuthorized –

    (errorCode=401, detailCode=4945)

    The credentials provided with the request in the session do not have write privileges on pid.

  • Exceptions.VersionMismatch –

    (errorCode=409, detailCode=4946)

    The provided serialVersion does not match the latest version that is held by the CN. The client should refresh it’s copy, verify that the update is still necessary, and resubmit the request with the updated information.
CNCore.delete(session, pid) → Identifier

Deletes an object from the entire DataONE system, including all nodes known to hold a copy of the object. The PID 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.

Use Cases:

UC16
Rest URL:

DELETE /object/{pid}
Parameters:
  • session (Types.Session) – Session information that contains the identity of the calling user as retrieved from the X.509 certificate which must be traceable to the CILogon service. The subject of the session defaults to the public user if the certificate was not provided with the request. Transmitted as part of the SSL handshake process.
  • pid (Types.Identifier) – The identifier of the object to be deleted. Transmitted as part of the URL path and must be escaped accordingly.
Returns:

The identifier of the object that was deleted.
Return type:

Types.Identifier
Raises:
CNCore.archive(session, pid) → Identifier

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.

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.

Rest URL:

PUT /archive/{pid}
Parameters:
  • session (Types.Session) – Session information that contains the identity of the calling user as retrieved from the X.509 certificate which must be traceable to the CILogon service. The subject of the session defaults to the public user if the certificate was not provided with the request. Transmitted as part of the SSL handshake process.
  • pid (Types.Identifier) – The identifier of the object to be archived. Transmitted as part of the URL path and must be escaped accordingly.
Returns:

The identifier of the object that was archived.
Return type:

Types.Identifier
Raises:
CNCore.listNodes() → NodeList

Returns a list of nodes that have been registered with the DataONE infrastructure.

Use Cases:

UC39
Rest URL:

GET /node
Returns:

List of nodes from the registry
Return type:

Types.NodeList
Raises:
CNCore.registerSystemMetadata(session, pid, sysmeta) → Identifier

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.

Rest URL:

POST /meta
Parameters:
  • session (Types.Session) – Session information that contains the identity of the calling user as retrieved from the X.509 certificate which must be traceable to the CILogon service. The subject of the session defaults to the public user if the certificate was not provided with the request. Transmitted as part of the SSL handshake process.
  • pid (Types.Identifier) – Transmitted as a UTF-8 String as a Param part of the MIME multipart/mixed message.
  • sysmeta (Types.SystemMetadata) – Transmitted as an UTF-8 encoded XML structure for the respective type as defined in the DataONE types schema, as a File part of the MIME multipart/mixed message.
Returns:

The pid that was updated.
Return type:

Types.Identifier
Raises:
CNCore.hasReservation(session, subject, pid) → boolean

Checks to determine if the supplied subject is the owner of the reservation of pid.

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.

Rest URL:

GET /reserve/{pid}?subject={subject}
Parameters:
  • session (Types.Session) – Session information that contains the identity of the calling user as retrieved from the X.509 certificate which must be traceable to an authority trusted by the DataONE Coordinating Nodes. Transmitted as part of the SSL handshake process.
  • subject (Types.Subject) – The subject of the principal (user) that made the reservation. Transmitted as a URL query parameter, and so must be escaped accordingly.
  • pid (Types.Identifier) – The identifier that is being checked for existing as a reserved identifier or is in use as an identifier for an existing object. Transmitted as part of the URL path and must be escaped accordingly.
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:
  • Exceptions.NotImplemented –

    (errorCode=501, detailCode=4920)

    The method functionality is not implemented.

  • Exceptions.ServiceFailure –

    (errorCode=500, detailCode=4921)

    An internal server error occurred.

  • Exceptions.InvalidToken –

    (errorCode=401, detailCode=4922)

    The session information is invalid.

  • Exceptions.NotFound –

    (errorCode=404, detailCode=4923)

    The PID does not exist as a reservation or an existing object and is not in use as an identifier.

  • Exceptions.NotAuthorized –

    (errorCode=401, detailCode=4924)

    The PID is reserved but the owner is not the principal identified by the subjectInfo OR the provide session does not have authority to access this service.

  • Exceptions.IdentifierNotUnique –

    (errorCode=409, detailCode=4925)

    The PID is in use to identify an already existing object in the DataONE system.

Read API

The CN_read 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.

Functions defined in CNRead
Tier REST Function Parameters
Tier 1 GET /object/{pid} get() (session, pid) -> Types.OctetStream
Tier 1 GET /meta/{pid} getSystemMetadata() (session, pid) -> Types.SystemMetadata
Tier 1 HEAD /object/{pid} describe() (session, pid) -> Types.DescribeResponse
Tier 1 GET /resolve/{pid} resolve() (session, pid) -> Types.ObjectLocationList
Tier 1 GET /checksum/{pid} getChecksum() (session, pid) -> Types.Checksum
Tier 1 GET /object[?fromDate={fromDate}&toDate={toDate}&formatId= {formatId}&replicaStatus={replicaStatus}&start={start}&count={count}] listObjects() (session, [fromDate], [toDate], [formatId], [replicaStatus], [start=0], [count=1000]) -> Types.ObjectList
Tier 1 GET /search/{queryType}/{query} search() (session, queryType, query) -> Types.ObjectList
Tier 1 GET /query/{queryEngine}/{query} query() (session, queryEngine, query) -> Types.OctetStream
Tier 1 GET /query/{queryType} getQueryEngineDescription() (session, queryEngine) -> Types.QueryEngineDescription
Tier 1 GET /query listQueryEngines() (session) -> Types.QueryEngineList
CNRead.get(session, pid) → OctetStream

Retrieves the object identified by pid 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.

Use Cases:

UC01, UC16, UC09
Rest URL:

GET /object/{pid}
Parameters:
  • session (Types.Session) – Session information that contains the identity of the calling user as retrieved from the X.509 certificate which must be traceable to the CILogon service. The subject of the session defaults to the public user if the certificate was not provided with the request. Transmitted as part of the SSL handshake process.
  • pid (Types.Identifier) – Identifier of the object to be retrieved Transmitted as part of the URL path and must be escaped accordingly.
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:

Types.OctetStream
Raises:

Example

See MNRead.get() for additional details and examples.

CNRead.getSystemMetadata(session, pid) → SystemMetadata

Returns the system metadata that contains DataONE specific information about the object identified by pid. Authoritative copies of system metadata are only available from the Coordinating Nodes.

Use Cases:

UC36, UC37, UC16
Rest URL:

GET /meta/{pid}
Parameters:
  • session (Types.Session) – Session information that contains the identity of the calling user as retrieved from the X.509 certificate which must be traceable to the CILogon service. The subject of the session defaults to the public user if the certificate was not provided with the request. Transmitted as part of the SSL handshake process.
  • pid (Types.Identifier) – Identifier for the object of interest. Transmitted as part of the URL path and must be escaped accordingly.
Returns:

A system metadata document describing the object.
Return type:

Types.SystemMetadata
Raises:

Example

See MNRead.getSystemMetadata() for additional details and examples.

CNRead.describe(session, pid) → DescribeResponse

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.

Use Cases:

UC16
Rest URL:

HEAD /object/{pid}
Parameters:
  • session (Types.Session) – Session information that contains the identity of the calling user as retrieved from the X.509 certificate which must be traceable to the CILogon service. The subject of the session defaults to the public user if the certificate was not provided with the request. Transmitted as part of the SSL handshake process.
  • pid (Types.Identifier) – Identifier for the object in question. Transmitted as part of the URL path and must be escaped accordingly.
Returns:

A set of values providing a basic description of the object.
Return type:

Types.DescribeResponse
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.resolve(session, pid) → ObjectLocationList

Returns a list of nodes (MNs or CNs) known to hold copies of the object identified by pid. 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.

Use Cases:

UC36, UC16
Rest URL:

GET /resolve/{pid}
Parameters:
  • session (Types.Session) – Session information that contains the identity of the calling user as retrieved from the X.509 certificate which must be traceable to the CILogon service. The subject of the session defaults to the public user if the certificate was not provided with the request. Transmitted as part of the SSL handshake process.
  • pid (Types.Identifier) – Identifier being resolved. Transmitted as part of the URL path and must be escaped accordingly.
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:

Types.ObjectLocationList
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.getChecksum(session, pid) → Checksum

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.

Use Cases:

UC09
Rest URL:

GET /checksum/{pid}
Parameters:
  • session (Types.Session) – Session information that contains the identity of the calling user as retrieved from the X.509 certificate which must be traceable to the CILogon service. The subject of the session defaults to the public user if the certificate was not provided with the request. Transmitted as part of the SSL handshake process.
  • pid (Types.Identifier) – Identifier of the object for which checksum is being requested Transmitted as part of the URL path and must be escaped accordingly.
Returns:

The checksum of the specified object
Return type:

Types.Checksum
Raises:
CNRead.listObjects(session[, fromDate][, toDate][, formatId][, replicaStatus][, start=0][, count=1000]) → ObjectList

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.

Use Cases:

UC06, UC16
Rest URL:

GET /object[?fromDate={fromDate}&toDate={toDate}&formatId= {formatId}&replicaStatus={replicaStatus}&start={start}&count={count}]
Parameters:
  • session (Types.Session) – Session information that contains the identity of the calling user as retrieved from the X.509 certificate which must be traceable to the CILogon service. The subject of the session defaults to the public user if the certificate was not provided with the request. Transmitted as part of the SSL handshake process.
  • fromDate (Types.DateTime) – Entries with SystemMetadata.dateSysMetadataModified greater than or equal to (>=) fromDate must be returned. Transmitted as a URL query parameter, and so must be escaped accordingly.
  • toDate (Types.DateTime) – Entries with SystemMetadata.dateSysMetadataModified less than (<) toDate must be returned. Transmitted as a URL query parameter, and so must be escaped accordingly.
  • formatId (Types.ObjectFormatIdentifier) – Restrict results to the specified object format. Transmitted as a URL query parameter, and so must be escaped accordingly.
  • replicaStatus (boolean) – Indicates if replicated objects should be returned in the list (i.e. any entries present in the SystemMetadata.replica, objects that have been replicated to this node). If false, then no objects that have been replicated should be returned. If true, then any objects can be returned, regardless of replication status. The default value is true. Transmitted as a URL query parameter, and so must be escaped accordingly.
  • start=0 (integer) – The zero-based index of the first value, relative to the first record of the resultset that matches the parameters. Transmitted as a URL query parameter, and so must be escaped accordingly.
  • count=1000 (integer) – The maximum number of entries that should be returned in the response. The Member Node may return fewer and the caller should check the total in the response to determine if further pages may be retrieved. Transmitted as a URL query parameter, and so must be escaped accordingly.
Returns:

The list of PIDs that match the query criteria. If none match, an empty list is returned.
Return type:

Types.ObjectList
Raises:
CNRead.search(session, queryType, query) → ObjectList

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”

Use Cases:

UC02, UC16
Rest URL:

GET /search/{queryType}/{query}
Parameters:
  • session (Types.Session) – Session information that contains the identity of the calling user as retrieved from the X.509 certificate which must be traceable to the CILogon service. The subject of the session defaults to the public user if the certificate was not provided with the request. Transmitted as part of the SSL handshake process.
  • queryType (string) – Indicates which search engine will be used to handle the query. Currently supported search engines include: “SOLR”. Transmitted as part of the URL path and must be escaped accordingly.
  • query (string) – The remainder of the URL is passed verbatim to the respective search engine implementation. Hence it may contain additional path elements and query elements as determined by the functionality of the search engine. The caller is reponsible for providing a ‘?’ to indicate the start of the query string portion of the URL, as well as proper URL escaping. Transmitted as part of the URL path and must be escaped accordingly.
Returns:

A list of objects that match the specified search criteria
Return type:

Types.ObjectList
Raises:
CNRead.query(session, queryEngine, query) → OctetStream

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.

Note

This method is in DRAFT status and is scheduled for version 1.1 of the APIs

Use Cases:

UC02, UC16
Rest URL:

GET /query/{queryEngine}/{query}
Parameters:
  • session (Types.Session) – Session information that contains the identity of the calling user as retrieved from the X.509 certificate which must be traceable to the CILogon service. The subject of the session defaults to the public user if the certificate was not provided with the request. Transmitted as part of the SSL handshake process.
  • queryEngine (string) – Indicates which search engine will be used to handle the query. Supported search engines can be determined through the CNRead.listQueryEngines API call. Transmitted as part of the URL path and must be escaped accordingly.
  • query (string) – The remainder of the URL is passed verbatim to the respective search engine implementation. Hence it may contain additional path elements and query elements as determined by the functionality of the search engine. The caller is reponsible for providing a ‘?’ to indicate the start of the query string portion of the URL, as well as proper URL escaping. Transmitted as part of the URL path and must be escaped accordingly.
Returns:

The structure of the response is determined by the chosen search engine and parameters provided to it.
Return type:

Types.OctetStream
Raises:
CNRead.getQueryEngineDescription(session, queryEngine) → QueryEngineDescription

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.

Note

This method is in DRAFT status and is scheduled for version 1.1 of the APIs

Rest URL:

GET /query/{queryType}
Parameters:
  • session (Types.Session) – Session information that contains the identity of the calling user as retrieved from the X.509 certificate provided with the request. The certificate must be traceable to an authority recognized by DataONE, currently CILogon. Transmitted as part of the SSL handshake process.
  • queryEngine (string) – Indicates which query engine for which to provide descriptive metadata. Currently supported search engines can be determined through CNRead.listQueryEngines. Transmitted as part of the URL path and must be escaped accordingly.
Returns:

A list of fields that are supported by the search index and additional metadata.
Return type:

Types.QueryEngineDescription
Raises:
CNRead.listQueryEngines(session) → QueryEngineList

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.

Note

This method is in DRAFT status and is scheduled for version 1.1 of the APIs

Rest URL:

GET /query
Parameters:

session (Types.Session) – Session information that contains the identity of the calling user as retrieved from the X.509 certificate provided with the request. The certificate must be traceable to an authority recognized by DataONE, currently CILogon. Transmitted as part of the SSL handshake process.
Returns:

A list of names of queryEngines available to the user identified by session.
Return type:

Types.QueryEngineList
Raises:

Authorization API

Functions defined in CNAuthorization
Tier REST Function Parameters
Tier 2 PUT /owner/{pid} setRightsHolder() (session, pid, userId, serialVersion) -> Types.Identifier
Tier 2 GET /isAuthorized/{pid}?action={action} isAuthorized() (session, pid, action) -> boolean
Tier 2 PUT /accessRules/{pid} setAccessPolicy() (session, pid, accessPolicy, serialVersion) -> boolean
CNAuthorization.setRightsHolder(session, pid, userId, serialVersion) → Identifier

Changes ownership (RightsHolder) of the specified object to the subject specified by userId

Use Cases:

UC16
Rest URL:

PUT /owner/{pid}
Parameters:
  • session (Types.Session) – Session information that contains the identity of the calling user as retrieved from the X.509 certificate which must be traceable to the CILogon service. The subject of the session defaults to the public user if the certificate was not provided with the request. Transmitted as part of the SSL handshake process.
  • pid (Types.Identifier) – Identifier of the object to be modified. Transmitted as part of the URL path and must be escaped accordingly.
  • userId (Types.Subject) – The subject that will be taking ownership of the specified object. Transmitted as a UTF-8 String as a Param part of the MIME multipart/mixed message.
  • serialVersion (unsigned long) – The serialVersion of the system metadata that is the intended target for the change. Transmitted as a UTF-8 String as a Param part of the MIME multipart/mixed message.
Returns:

Identifier of the object that was modified
Return type:

Types.Identifier
Raises:
CNAuthorization.isAuthorized(session, pid, action) → boolean

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.

Note

Should perhaps add convenience methods for “canRead()” and “canWrite()” to verify that a user is able to read / write an object.

Use Cases:

UC01, UC02, UC36, UC37
Rest URL:

GET /isAuthorized/{pid}?action={action}
Parameters:
  • session (Types.Session) – Session information that contains the identity of the calling user as retrieved from the X.509 certificate which must be traceable to the CILogon service. The subject of the session defaults to the public user if the certificate was not provided with the request. Transmitted as part of the SSL handshake process.
  • pid (Types.Identifier) – The identifer of the resource for which access is being checked. Transmitted as part of the URL path and must be escaped accordingly.
  • action (Types.Permission) – The type of operation which is being requested for the given pid. Transmitted as a URL query parameter, and so must be escaped accordingly.
Returns:

True if the operation is allowed
Return type:

boolean
Raises:
CNAuthorization.setAccessPolicy(session, pid, accessPolicy, serialVersion) → boolean

Sets the access permissions for an object identified by pid.

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.

Use Cases:

UC16
Rest URL:

PUT /accessRules/{pid}
Parameters:
  • session (Types.Session) – Session information that contains the identity of the calling user as retrieved from the X.509 certificate which must be traceable to the CILogon service. The subject of the session defaults to the public user if the certificate was not provided with the request. Transmitted as part of the SSL handshake process.
  • pid (Types.Identifier) – The object for which access control is being updated. Transmitted as part of the URL path and must be escaped accordingly.
  • accessPolicy (Types.AccessPolicy) – The desired privileges to be assigned to the object. Transmitted as an UTF-8 encoded XML structure for the respective type as defined in the DataONE types schema, as a File part of the MIME multipart/mixed message.
  • serialVersion (unsigned long) – The serialVersion of the system metadata that is the intended target for the change. Transmitted as a UTF-8 String as a Param part of the MIME multipart/mixed message.
Returns:

True if the operation succeeds, otherwise false.
Return type:

boolean
Raises:

Identity API

Functions defined in CNIdentity
Tier REST Function Parameters
Tier 2 POST /accounts registerAccount() (session, person) -> Types.Subject
Tier 2 PUT /accounts/{subject} updateAccount() (session, subject, person) -> Types.Subject
Tier 2 PUT /accounts/verification/{subject} verifyAccount() (session, subject) -> boolean
Tier 2 GET /accounts/{subject} getSubjectInfo() (session, subject) -> Types.SubjectInfo
Tier 2 GET /accounts?query={query}[&status={status}&start={start}&count={count}] listSubjects() (session, query, status, start, count) -> Types.SubjectInfo
Tier 2 POST /accounts/map mapIdentity() (session, primarySubject, secondarySubject) -> boolean
Tier 2 DELETE /accounts/map/{subject} removeMapIdentity() (session, subject) -> boolean
Tier 2 POST /accounts/pendingmap requestMapIdentity() (session, subject) -> boolean
Tier 2 PUT /accounts/pendingmap/{subject} confirmMapIdentity() (session, subject) -> boolean
Tier 2 GET /accounts/pendingmap/{subject} getPendingMapIdentity() (session, subject) -> Types.SubjectInfo
Tier 2 DELETE /accounts/pendingmap/{subject} denyMapIdentity() (session, subject) -> boolean
Tier 2 POST /groups createGroup() (session, group) -> Types.Subject
Tier 2 PUT /groups updateGroup() (session, group) -> boolean
CNIdentity.registerAccount(session, person) → Subject

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.

Use Cases:

UC16
Rest URL:

POST /accounts
Parameters:
  • session (Types.Session) – Session information that contains the identity of the calling user as retrieved from the X.509 certificate which must be traceable to the CILogon service. The subject of the session defaults to the public user if the certificate was not provided with the request. Transmitted as part of the SSL handshake process.
  • person (Types.Person) – Information about the Person to be registered with the account, including the real name and email address for the individual. The Subject with the Person must match the subject of the X.509 certificate associated with the authenticated SSL session via client-side authentication, and must not have been registered previously. Transmitted as an UTF-8 encoded XML structure for the respective type as defined in the DataONE types schema, as a File part of the MIME multipart/mixed message.
Returns:

The new subject in the DataONE system. This may be a simple identifier.
Return type:

Types.Subject
Raises:
CNIdentity.updateAccount(session, subject, person) → 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.

Use Cases:

UC16
Rest URL:

PUT /accounts/{subject}
Parameters:
  • session (Types.Session) – Session information that contains the identity of the calling user as retrieved from the X.509 certificate which must be traceable to the CILogon service. The subject of the session defaults to the public user if the certificate was not provided with the request. Transmitted as part of the SSL handshake process.
  • subject (Types.Subject) – The subject of the person being updated. Transmitted as part of the URL path and must be escaped accordingly.
  • person (Types.Person) – New information about the Person. The subject of the Person cannot be updated with this method and must match the subject of the X.509 certificate associated with the authenticated SSL session via client-side authentication. Transmitted as an UTF-8 encoded XML structure for the respective type as defined in the DataONE types schema, as a File part of the MIME multipart/mixed message.
Returns:

The Subject in the DataONE system that was updated.
Return type:

Types.Subject
Raises:
CNIdentity.verifyAccount(session, subject) → boolean

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.

Rest URL:

PUT /accounts/verification/{subject}
Parameters:
  • session (Types.Session) – Session information that contains the identity of the calling user as retrieved from the X.509 certificate which must be traceable to the CILogon service. The subject of the session defaults to the public user if the certificate was not provided with the request. Transmitted as part of the SSL handshake process.
  • subject (Types.Subject) – The Subject identifier of the Person to be verified. After this service is called for a subject by an authorized user, the account is marked as verified by this user. Transmitted as part of the URL path and must be escaped accordingly.
Returns:

True if the account verification succeeds, otherwise false.
Return type:

boolean
Raises:
CNIdentity.getSubjectInfo(session, subject) → SubjectInfo

Get the information about a Person (their equivalent identities, and the Groups to which they belong) or the Group (including members).

Use Cases:

UC12
Rest URL:

GET /accounts/{subject}
Parameters:
  • session (Types.Session) – Session information that contains the identity of the calling user as retrieved from the X.509 certificate which must be traceable to the CILogon service. The subject of the session defaults to the public user if the certificate was not provided with the request. Transmitted as part of the SSL handshake process.
  • subject (Types.Subject) – The Subject identifier of the Person or Group details to be returned. Transmitted as part of the URL path and must be escaped accordingly.
Returns:

The Person or Group details are contained in the returned SubjectList for the given Subject
Return type:

Types.SubjectInfo
Raises:
CNIdentity.listSubjects(session, query, status, start, count) → SubjectInfo

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.

Rest URL:

GET /accounts?query={query}[&status={status}&start={start}&count={count}]
Parameters:
  • session (Types.Session) – Session information that contains the identity of the calling user as retrieved from the X.509 certificate which must be traceable to the CILogon service. The subject of the session defaults to the public user if the certificate was not provided with the request. Transmitted as part of the SSL handshake process.
  • query (string) – A query string criteria to be matched using a case-insensitive substring match against the identifier for the principal, the givenName or familyName of users, and the groupName of groups. The function returns the union of all successful matches against these fields. Transmitted as a URL query parameter, and so must be escaped accordingly.
  • status (string) – When provided, the status field can limit the returned list of Subjects to only those with the given status. Currently the ‘verified’ status is supported. Transmitted as a URL query parameter, and so must be escaped accordingly.
  • start (integer) – The starting record number for the records to be returned (default = 0). Transmitted as a URL query parameter, and so must be escaped accordingly.
  • count (integer) – The maximum number of entries that should be returned in the response. The Member Node may return fewer and the caller should check the total in the response to determine if further pages may be retrieved (default = 100). Transmitted as a URL query parameter, and so must be escaped accordingly.
Returns:

The list of people and groups that match the query.
Return type:

Types.SubjectInfo
Raises:
CNIdentity.mapIdentity(session, primarySubject, secondarySubject) → boolean

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.

Rest URL:

POST /accounts/map
Parameters:
  • session (Types.Session) – Session information that contains the identity of the calling user as retrieved from the X.509 certificate which must be traceable to the CILogon service. Transmitted as part of the SSL handshake process.
  • primarySubject (Types.Subject) – The Subject identifier that will have a mapped identity to the other given subject. Transmitted as a UTF-8 String as a Param part of the MIME multipart/mixed message.
  • secondarySubject (Types.Subject) – The Subject identifier that will have a mapped identity to the other given subject. Transmitted as a UTF-8 String as a Param part of the MIME multipart/mixed message.
Returns:

True if the mapping was successfully initiated, false otherwise.
Return type:

boolean
Raises:
CNIdentity.removeMapIdentity(session, subject) → boolean

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.

Rest URL:

DELETE /accounts/map/{subject}
Parameters:
  • session (Types.Session) – Session information that contains the identity of the calling user as retrieved from the X.509 certificate which must be traceable to the CILogon service. Transmitted as part of the SSL handshake process.
  • subject (Types.Subject) – The Subject identifier to be used for equivalentIdentity. This Subject will not match the Subject named in the certificate. Transmitted as part of the URL path and must be escaped accordingly.
Returns:

True if the map was successfully created, false otherwise.
Return type:

boolean
Raises:
CNIdentity.requestMapIdentity(session, subject) → boolean

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.

Rest URL:

POST /accounts/pendingmap
Parameters:
  • session (Types.Session) – Session information that contains the identity of the calling user as retrieved from the X.509 certificate which must be traceable to the CILogon service. Transmitted as part of the SSL handshake process.
  • subject (Types.Subject) – The Subject identifier to be used for equivalentIdentity. This Subject will not match the Subject named in the certificate. Transmitted as a UTF-8 String as a Param part of the MIME multipart/mixed message.
Returns:

True if the mapping was successfully initiated, false otherwise.
Return type:

boolean
Raises:
CNIdentity.confirmMapIdentity(session, subject) → boolean

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.

Rest URL:

PUT /accounts/pendingmap/{subject}
Parameters:
  • session (Types.Session) – Session information that contains the identity of the calling user as retrieved from the X.509 certificate which must be traceable to the CILogon service. Transmitted as part of the SSL handshake process.
  • subject (Types.Subject) – The Subject identifier to be used for equivalentIdentity. This Subject will not match the Subject named in the certificate. Transmitted as part of the URL path and must be escaped accordingly.
Returns:

True if the map was successfully created, false otherwise.
Return type:

boolean
Raises:
CNIdentity.getPendingMapIdentity(session, subject) → SubjectInfo

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.

Rest URL:

GET /accounts/pendingmap/{subject}
Parameters:
  • session (Types.Session) – Session information that contains the identity of the calling user as retrieved from the X.509 certificate which must be traceable to the CILogon service. Transmitted as part of the SSL handshake process.
  • subject (Types.Subject) – The Subject identifier to be used for equivalentIdentity. This Subject will not match the Subject named in the certificate. Transmitted as part of the URL path and must be escaped accordingly.
Returns:

The SubjectInfo
Return type:

Types.SubjectInfo
Raises:
CNIdentity.denyMapIdentity(session, subject) → boolean

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.

Rest URL:

DELETE /accounts/pendingmap/{subject}
Parameters:
  • session (Types.Session) – Session information that contains the identity of the calling user as retrieved from the X.509 certificate which must be traceable to the CILogon service. Transmitted as part of the SSL handshake process.
  • subject (Types.Subject) – The Subject identifier to be used for equivalentIdentity. This Subject will not match the Subject named in the certificate. Transmitted as part of the URL path and must be escaped accordingly.
Returns:

True if the map was successfully created, false otherwise.
Return type:

boolean
Raises:
CNIdentity.createGroup(session, group) → Subject

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.

Rest URL:

POST /groups
Parameters:
  • session (Types.Session) – Session information that contains the identity of the calling user as retrieved from the X.509 certificate which must be traceable to the CILogon service. The subject of the session defaults to the public user if the certificate was not provided with the request. Transmitted as part of the SSL handshake process.
  • group (Types.Group) – The Group to be created. Transmitted as an UTF-8 encoded XML structure for the respective type as defined in the DataONE types schema, as a File part of the MIME multipart/mixed message.
Returns:

The Subject of the group that was created.
Return type:

Types.Subject
Raises:
CNIdentity.updateGroup(session, group) → boolean

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.

Rest URL:

PUT /groups
Parameters:
  • session (Types.Session) – Session information that contains the identity of the calling user as retrieved from the X.509 certificate which must be traceable to the CILogon service. The subject of the session is used to determine if the request is being made by the creator of the group. Transmitted as part of the SSL handshake process.
  • group (Types.Group) – The new Group object that will replace the old Group. The Group.Subject must match the groupName and an update cannot modify this value. Transmitted as an UTF-8 encoded XML structure for the respective type as defined in the DataONE types schema, as a File part of the MIME multipart/mixed message.
Returns:

True if the group that was modified successfully, false otherwise
Return type:

boolean
Raises:

Replication API

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.

Functions defined in CNReplication
Tier REST Function Parameters
Tier 4 PUT /replicaNotifications/{pid} setReplicationStatus() (session, pid, nodeRef, status, failure) -> boolean
Tier 4 PUT /replicaMetadata/{pid} updateReplicationMetadata() (session, pid, replicaMetadata, serialVersion) -> boolean
Tier 4 PUT /replicaPolicies/{pid} setReplicationPolicy() (session, pid, policy, serialVersion) -> boolean
Tier 4 GET /replicaAuthorizations/{pid}?targetNodeSubject={targetNodeSubject} isNodeAuthorized() (session, targetNodeSubject, pid) -> boolean
  PUT /removeReplicaMetadata/{pid} deleteReplicationMetadata() (session, pid, nodeId, serialVersion) -> boolean
CNReplication.setReplicationStatus(session, pid, nodeRef, status, failure) → boolean

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.

Use Cases:

UC09
Rest URL:

PUT /replicaNotifications/{pid}
Parameters:
  • session (Types.Session) – Session information that contains the identity of the calling user as retrieved from the X.509 certificate which must be traceable to the CILogon service. The subject of the session defaults to the public user if the certificate was not provided with the request. Transmitted as part of the SSL handshake process.
  • pid (Types.Identifier) – Identifier of the object to be replicated between Member Nodes. Transmitted as part of the URL path and must be escaped accordingly.
  • nodeRef (Types.NodeReference) – Reference to the Node which made the setReplicationStatus call. If this is a Member Node, the checksum must be compared with that of the authoritative Member Node. If not, this step can be ignored as the call is not signifying a replication is complete. Transmitted as a UTF-8 String as a Param part of the MIME multipart/mixed message.
  • status (Types.ReplicationStatus) – Replication status. See system metadata schema for possible values. Transmitted as a UTF-8 String as a Param part of the MIME multipart/mixed message.
  • failure (Types.BaseException) – A BaseException object or one of it’s subclasses, or null. If the status is set to ‘failed’, this exception object can provide more detail. Appropriate sub-classes include InsufficientResource, NotAuthorized, ServiceFailure, etc. Transmitted as an UTF-8 encoded XML structure for the respective type as defined in the DataONE types schema, as a File part of the MIME multipart/mixed message.
Returns:

True if the operation is allowed and expected, otherwise an exception should be raised.
Return type:

boolean
Raises:
CNReplication.updateReplicationMetadata(session, pid, replicaMetadata, serialVersion) → boolean

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.

Rest URL:

PUT /replicaMetadata/{pid}
Parameters:
  • session (Types.Session) – Session information that contains the identity of the calling user as retrieved from the X.509 certificate which must be traceable to the CILogon service. Transmitted as part of the SSL handshake process.
  • pid (Types.Identifier) – Transmitted as part of the URL path and must be escaped accordingly.
  • replicaMetadata (Types.Replica) – Transmitted as an UTF-8 encoded XML structure for the respective type as defined in the DataONE types schema, as a File part of the MIME multipart/mixed message.
  • serialVersion (unsigned long) – The serialVersion of the system metadata that is the intended target for the change. Transmitted as a UTF-8 String as a Param part of the MIME multipart/mixed message.
Returns:

True on success
Return type:

boolean
Raises:
CNReplication.setReplicationPolicy(session, pid, policy, serialVersion) → boolean

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.

Rest URL:

PUT /replicaPolicies/{pid}
Parameters:
  • session (Types.Session) – Session information that contains the identity of the calling user as retrieved from the X.509 certificate which must be traceable to the CILogon service. The subject of the session defaults to the public user if the certificate was not provided with the request. Transmitted as part of the SSL handshake process.
  • pid (Types.Identifier) – Transmitted as part of the URL path and must be escaped accordingly.
  • policy (Types.ReplicationPolicy) – Transmitted as an UTF-8 encoded XML structure for the respective type as defined in the DataONE types schema, as a File part of the MIME multipart/mixed message.
  • serialVersion (unsigned long) – The serialVersion of the system metadata that is the intended target for the change. Transmitted as a UTF-8 String as a Param part of the MIME multipart/mixed message.
Returns:

True on success
Return type:

boolean
Raises:
CNReplication.isNodeAuthorized(session, targetNodeSubject, pid) → boolean

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.

Rest URL:

GET /replicaAuthorizations/{pid}?targetNodeSubject={targetNodeSubject}
Parameters:
  • session (Types.Session) – Session information that contains the identity of the calling user as retrieved from the X.509 certificate which must be traceable to the CILogon service. The subject of the session defaults to the public user if the certificate was not provided with the request. Transmitted as part of the SSL handshake process.
  • targetNodeSubject (Types.Subject) – The subject that identifies the target node, with a value extracted from the X.509 certificate passed in during the call to MNReplication.replicate(). Transmitted as a URL query parameter, and so must be escaped accordingly.
  • pid (Types.Identifier) – The identifier of the object to be replicated. Transmitted as part of the URL path and must be escaped accordingly.
Returns:

True on success
Return type:

boolean
Raises:
CNReplication.deleteReplicationMetadata(session, pid, nodeId, serialVersion) → boolean

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 is normally only called by Coordinating Nodes.

Rest URL:

PUT /removeReplicaMetadata/{pid}
Parameters:
  • session (Types.Session) – Session information that contains the identity of the calling user as retrieved from the X.509 certificate which must be traceable to the CILogon service. The subject of the session MUST be a Coordinating Node. Transmitted as part of the SSL handshake process.
  • pid (Types.Identifier) – The identifier of the object whose replication metadata is being modified. Transmitted as part of the URL path and must be escaped accordingly.
  • nodeId (Types.NodeReference) – The identifier of the node replication information that is being removed from the system metadata record. Transmitted as a UTF-8 String as a Param part of the MIME multipart/mixed message.
  • serialVersion (unsigned long) – The Types.SystemMetadata.serialVersion of the system metadata being updated. This MUST match the latest version of system metadata available for the object on the Coordinating Node. Transmitted as a UTF-8 String as a Param part of the MIME multipart/mixed message.
Returns:

True if the replication metadata was successfully deleted.
Return type:

boolean
Raises:
  • Exceptions.NotImplemented –

    (errorCode=501, detailCode=4950)

    The method functionality if not fully implemented

  • Exceptions.ServiceFailure –

    (errorCode=500, detailCode=4951)

    An internal server error occurred that prevented the operation from completing.

  • Exceptions.InvalidRequest –

    (errorCode=400, detailCode=4952)

    The request parameters are malformed

  • Exceptions.InvalidToken –

    (errorCode=401, detailCode=4953)

    The supplied session is invalid

  • Exceptions.NotFound –

    (errorCode=404, detailCode=4956)

    The object identified by pid or the node reference specified by nodeId could not be located in the system metadata for the object.

  • Exceptions.NotAuthorized –

    (errorCode=401, detailCode=4954)

    The subject identified by the session information does not have appropriate priviledges for modifiying the content or accessing the service.

  • Exceptions.VersionMismatch –

    (errorCode=409, detailCode=4955)

    The serialVersion does not match the current Types.SystemMetadata.serialVersion value of the object system metadata.

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

CNReplication.getMNReplicateList()
CNReplication.getReplicationPolicy(sess, ID)
CNReplication.isReplicationNeeded()
CNReplication.replicateMetadata()
CNReplication.setDefaultReplicationPolicy(sess, policy)
CNReplication.setReplicationPolicy(sess, policy, ID)

Register API

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.

Functions defined in CNRegister
Tier REST Function Parameters
Tier 2 PUT /node/{nodeid} updateNodeCapabilities() (session, nodeid, node) -> boolean
Tier 2 POST /node register() (session, node) -> Types.NodeReference
CNRegister.updateNodeCapabilities(session, nodeid, node) → boolean

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.

Rest URL:

PUT /node/{nodeid}
Parameters:
  • session (Types.Session) – Session information that contains the identity of the calling user as retrieved from the X.509 certificate which must be traceable to the CILogon service. The subject of the session defaults to the public user if the certificate was not provided with the request. Transmitted as part of the SSL handshake process.
  • nodeid (Types.NodeReference) – The identifier of the existing node entry being updated. Transmitted as part of the URL path and must be escaped accordingly.
  • node (Types.Node) – An instance of :class`Types.Node` that contains the updated information. Transmitted as an UTF-8 encoded XML structure for the respective type as defined in the DataONE types schema, as a File part of the MIME multipart/mixed message.
Returns:

True if operation is successful
Return type:

boolean
Raises:
CNRegister.register(session, node) → NodeReference

Register a new node in the system. If the node already exists, then a IdentifierNotUnique exception MUST be returned.

Rest URL:

POST /node
Parameters:
  • session (Types.Session) – Session information that contains the identity of the calling user as retrieved from the X.509 certificate which must be traceable to the CILogon service. The subject of the session defaults to the public user if the certificate was not provided with the request. Transmitted as part of the SSL handshake process.
  • node (Types.Node) – An instance of Types.Node that fully describes the node being registered. Note that some attributes will be set by the Coordinating Node. Transmitted as an UTF-8 encoded XML structure for the respective type as defined in the DataONE types schema, as a File part of the MIME multipart/mixed message.
Returns:

The identifier of the new node entry if successful, otherwise an error is raised.
Return type:

Types.NodeReference
Raises:

Table Of Contents

Related Topics

© Copyright 2009-2014, DataONE. [ Page Source | Revision History ]  

This material is based upon work supported by the National Science Foundation under Grant Number 083094. Any opinions, findings, and conclusions or recommendations expressed in this material are those of the author(s) and do not necessarily reflect the views of the National Science Foundation.