D1MemberNode
DataONE Member Node Services.
The following resources are applicable:
- /v1
- /v1/checksum/{pid}
- /v1/error
- /v1/isAuthorized/{pid}
- /v1/log
- /v1/meta/{pid}
- /v1/monitor/ping
- /v1/node
- /v1/object
- /v1/object/{pid}
- /v1/query
- /v1/query/{queryEngine}/{query}
- /v1/query/{queryType}
- /v1/replica/{pid}
Mount Point: /mn
GET
Response Body
| element: | (custom) |
| media types: | application/xml |
(no documentation provided)
/v1
Mount Point: /mn/v1
GET
Response Body
| element: | (custom) |
| media types: | application/xml |
(no documentation provided)
/v1/checksum/{pid}
Mount Point: /mn/v1/checksum/{pid}
GET
Represents the value of a computed :term:`checksum` expressed as a hexadecimal formatted version of the message digest. Note that these hex values should be treated as case-insensitive strings, in that leading zeros must be preserved, and digests can use a mixture of upper and lower case letters to represent the hex values. Comparison algorithms MUST be able to handle any variant of these representations (e.g., by performing a case-insensitive string match on hex digests from the same algorithm). Rest URL: GET /checksum/{pid}[?checksumAlgorithm={checksumAlgorithm}] Schema fragment(s) for this class:
<xs:complexType xmlns:ns="http://ns.dataone.org/service/types/v1" xmlns:xs="http://www.w3.org/2001/XMLSchema" name="Checksum"> <xs:simpleContent> <xs:extension base="xs:string"> <xs:attribute type="xs:string" use="required" name="algorithm"/> </xs:extension> </xs:simpleContent> </xs:complexType>
Parameters
| name | description | type | default |
|---|---|---|---|
| pid | (Types.Identifier) – The identifier of the object the operation is being performed on. Transmitted as part of the URL path and must be escaped accordingly. | path | |
| checksumAlgorithm | (string) – The name of an algorithm that will be used to compute a checksum of the bytes of the object. This value is drawn from a DataONE controlled list of values as indicted in the Types.SystemMetadata. If not specified, then the system wide default checksum algorithm should be used. Transmitted as a URL query parameter, and so must be escaped accordingly. | query |
Response Body
| element: | (custom) |
| media types: | application/xml |
Returns a Types.Checksum for the specified object using an accepted hashing algorithm. The result is used to determine if two instances referenced by a PID are identical, hence it is necessary that MNs can ensure that the returned checksum is valid for the referenced object either by computing it on the fly or by using a cached value that is certain to be correct.
/v1/error
Mount Point: /mn/v1/error
POST
This is a callback method used by a CN to indicate to a MN that it cannot complete synchronization of the science metadata identified by pid. When called, the MN should take steps to record the problem description and notify an administrator or the data owner of the issue. A successful response is indicated by a HTTP status of 200. An unsuccessful call is indicated by a returned exception and associated HTTP status code. Access control for this method MUST be configured to allow calling by Coordinating Nodes and MAY be configured to allow more general access. Use Cases: UC06 Rest URL: POST /error Optionally raised by the receiving MN, depending on implementation.
Parameters
| name | description | type | default |
|---|---|---|---|
| message | message (Types.Exception) – An instance of the Exceptions.SynchronizationFailed exception with body appropriately filled. 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. | formdata |
Response Body
| element: | (custom) |
| media types: | application/xml |
Types.Boolean A successful response is indicated by a HTTP 200 status. An unsuccessful call is indicated by returning the appropriate exception.
/v1/isAuthorized/{pid}
Mount Point: /mn/v1/isAuthorized/{pid}
GET
Parameters
| name | description | type | default |
|---|---|---|---|
| pid | (no documentation provided) | path | |
| action | (no documentation provided) | query |
Response Body
| element: | (custom) |
| media types: | application/xml |
(no documentation provided)
/v1/log
Mount Point: /mn/v1/log
GET
Represents a collection of :class:`Types.LogEntry` elements, used to transfer log information between DataONE components. Schema fragment(s) for this class:
<xs:complexType xmlns:ns="http://ns.dataone.org/service/types/v1" xmlns:xs="http://www.w3.org/2001/XMLSchema" name="Log"> <xs:complexContent> <xs:extension base="ns:Slice"> <xs:sequence> <xs:element type="ns:LogEntry" name="logEntry" minOccurs="0" maxOccurs="unbounded"/> </xs:sequence> </xs:extension> </xs:complexContent> </xs:complexType>A single log entry as reported by a Member Node or Coordinating Node through the :func:`MNCore.getLogRecords` or :func:`CNCore.getLogRecords` methods. Schema fragment(s) for this class:
<xs:complexType xmlns:ns="http://ns.dataone.org/service/types/v1" xmlns:xs="http://www.w3.org/2001/XMLSchema" name="LogEntry"> <xs:sequence> <xs:element type="xs:string" name="entryId" minOccurs="1" maxOccurs="1"/> <xs:element type="ns:Identifier" name="identifier" minOccurs="1" maxOccurs="1"/> <xs:element type="xs:string" name="ipAddress" minOccurs="1" maxOccurs="1"/> <xs:element type="xs:string" name="userAgent" minOccurs="1" maxOccurs="1"/> <xs:element type="ns:Subject" name="subject" minOccurs="1" maxOccurs="1"/> <xs:element type="ns:Event" name="event" minOccurs="1" maxOccurs="1"/> <xs:element type="xs:dateTime" name="dateLogged" minOccurs="1" maxOccurs="1"/> <xs:element type="ns:NodeReference" name="nodeIdentifier" minOccurs="1" maxOccurs="1"/> </xs:sequence> </xs:complexType>Example Response:
Parameters
| name | description | type | default |
|---|---|---|---|
| fromDate | fromDate (Types.DateTime) – Records with time stamp greater than or equal to (>=) this value will be returned. Transmitted as a URL query parameter, and so must be escaped accordingly. | query | |
| toDate | toDate (Types.DateTime) – Records with a time stamp 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. | query | |
| event | 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. | query | |
| pidFilter | 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 Member Node implementation with no warning. Accepts PIDs and SIDs Transmitted as a URL query parameter, and so must be escaped accordingly. | query | |
| start | start=0 (integer) – Optional zero based offset from the first record in the set of matching log records. Used to assist with paging the response. Transmitted as a URL query parameter, and so must be escaped accordingly. | query | 0 |
| count | count=1000 (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. | query | 1000 |
Response Body
| element: | (custom) |
| media types: | application/xml |
Types.Log
/v1/meta/{pid}
Mount Point: /mn/v1/meta/{pid}
GET
Describes the object identified by id by returning the associated system metadata object. If the object does not exist on the node servicing the request, then Exceptions.NotFound MUST be raised even if the object exists on another node in the DataONE system. Use Cases: UC06, UC37, UC16 Rest URL: GET /meta/{pid} Schema fragment(s) for this class:
<xs:complexType xmlns:ns="http://ns.dataone.org/service/types/v1" xmlns:xs="http://www.w3.org/2001/XMLSchema" name="SystemMetadata"> <xs:sequence> <xs:element type="xs:long" name="serialVersion" minOccurs="0" maxOccurs="1"/> <xs:element type="ns:Identifier" name="identifier"/> <xs:element type="ns:ObjectFormatIdentifier" name="formatId"/> <xs:element type="xs:long" name="size"/> <xs:element type="ns:Checksum" name="checksum"/> <xs:element type="ns:Subject" name="submitter" minOccurs="0" maxOccurs="1"/> <xs:element type="ns:Subject" name="rightsHolder"/> <xs:element type="ns:AccessPolicy" name="accessPolicy" minOccurs="0" maxOccurs="1"/> <xs:element type="ns:ReplicationPolicy" name="replicationPolicy" minOccurs="0" maxOccurs="1"/> <xs:element type="ns:Identifier" name="obsoletes" minOccurs="0" maxOccurs="1"/> <xs:element type="ns:Identifier" name="obsoletedBy" minOccurs="0" maxOccurs="1"/> <xs:element type="xs:boolean" name="archived" minOccurs="0" maxOccurs="1"/> <xs:element type="xs:dateTime" name="dateUploaded" minOccurs="0" maxOccurs="1"/> <xs:element type="xs:dateTime" name="dateSysMetadataModified" minOccurs="0" maxOccurs="1"/> <xs:element type="ns:NodeReference" name="originMemberNode" minOccurs="0" maxOccurs="1"/> <xs:element type="ns:NodeReference" name="authoritativeMemberNode" minOccurs="0" maxOccurs="1"/> <xs:element type="ns:Replica" name="replica" minOccurs="0" maxOccurs="unbounded"/> </xs:sequence> </xs:complexType>
Parameters
| name | description | type | default |
|---|---|---|---|
| pid | (Types.Identifier) – Identifier for the science data or science metedata object of interest. May be either a PID or a SID. Transmitted as part of the URL path and must be escaped accordingly. | path |
Response Body
| element: | (custom) |
| media types: | application/xml |
Types.SystemMetadata. System metadata object describing the object.
/v1/monitor/ping
Mount Point: /mn/v1/monitor/ping
GET
Response Body
| element: | (custom) |
| media types: | application/xml |
(no documentation provided)
/v1/node
Mount Point: /mn/v1/node
GET
Response Body
| element: | (custom) |
| media types: | application/xml |
(no documentation provided)
/v1/object
Mount Point: /mn/v1/object
GET
Retrieve the list of objects present on the MN that match the calling parameters. This method is required to support the process of Member Node synchronization. At a minimum, this method MUST be able to return a list of objects that match: fromDate < SystemMetadata.dateSysMetadataModified but is expected to also support date range (by also specifying toDate), and should also support slicing of the matching set of records by indicating the starting index of the response (where 0 is the index of the first item) and the count of elements to be returned. Note that date time precision is limited to one millisecond. If no timezone information is provided, the UTC will be assumed. Use Cases: UC06, UC16 Rest URL: GET /object[?fromDate={fromDate}&toDate={toDate}&identifier={identifier}&formatId={formatId}&replicaStatus={replicaStatus} &start={start}&count={count}] Schema fragment(s) for this class:
<xs:complexType xmlns:ns="http://ns.dataone.org/service/types/v1" xmlns:xs="http://www.w3.org/2001/XMLSchema" name="ObjectInfo"> <xs:sequence> <xs:element type="ns:Identifier" name="identifier" minOccurs="1" maxOccurs="1"/> <xs:element type="ns:ObjectFormatIdentifier" name="formatId"/> <xs:element type="ns:Checksum" name="checksum" minOccurs="1" maxOccurs="1"/> <xs:element type="xs:dateTime" name="dateSysMetadataModified"/> <xs:element type="xs:long" name="size"/> </xs:sequence> </xs:complexType>
Parameters
| name | description | type | default |
|---|---|---|---|
| identifier | (Types.Identifier) – Restrict results to the specified identifier. May be a PID or a SID. In the case of the latter, returns a listing of all PIDs that share the given SID. Transmitted as a URL query parameter, and so must be escaped accordingly. | query | |
| fromDate | (Types.DateTime) – Entries with SystemMetadata.dateSysMetadataModified greater than (>) fromDate must be returned. Transmitted as a URL query parameter, and so must be escaped accordingly. | query | |
| 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. | query | |
| formatId | (Types.ObjectFormatIdentifier) – Restrict results to the specified object format identifier. Transmitted as a URL query parameter, and so must be escaped accordingly. | query | |
| replicaStatus | TBD | query | |
| start | 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. | query | |
| count | 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. | query |
Response Body
| element: | (custom) |
| media types: | application/xml |
Types.ObjectList The list of PIDs that match the query criteria. If none match, an empty list is returned.
/v1/object/{pid}
Mount Point: /mn/v1/object/{pid}
GET
Lookup DSpaceObject and Return in specific format. Default format will be used for standard DSpace PID. Alternate Formats may be provided in the future as alternate PID. PID May be any identifier configured in IdentifierService that may be used to resolve the object, examples may include DSpace handle id, CNRI Handles, DOI or other implemented identifiers. Retrieve an object identified by id from the node. Supports both PIDs and SIDs. SID will return HEAD PID. The response MUST contain the bytes of the indicated object, and the checksum of the bytes retrieved SHOULD match the SystemMetadata.checksum recorded in the Types.SystemMetadata when calling with PID. 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. Also implmented by Coordinating Nodes as CNRead.get(). Use Cases: UC01, UC06, UC16 Rest URL: GET /object/nnnbhj{id} hghb bmnb, b,b,bmb
Parameters
| name | description | type | default |
|---|---|---|---|
| pid | persistent identifier, must be resolve able in IdentifierService. (Types.Identifier) – The identifier for the object to be retrieved. May be a PID or a SID. Transmitted as part of the URL path and must be escaped accordingly. | path |
Response Body
| element: | (custom) |
| media types: | */* application/xml application/json |
Bytes of the specified object. Types.OctetStream
HEAD
This method provides a lighter weight mechanism than MNRead.getSystemMetadata() for a client to determine basic properties of the referenced object. The response should indicate properties that are typically returned in a HTTP HEAD request: the date late modified, the size of the object, the type of the object (the 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} 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-formatId: eml://ecoinformatics.org/eml-2.0.1 DataONE-Checksum: SHA-1,2e01e17467891f7c933dbaa00e1459d23db3fe4f DataONE-SerialVersion: 1234
Parameters
| name | description | type | default |
|---|---|---|---|
| pid | (Types.Identifier) – Identifier for the object in question. May be either a PID or a SID. Transmitted as part of the URL path and must be escaped accordingly. | path |
Response Body
| element: | (custom) |
| media types: | application/xml |
Types.DescribeResponse A set of values providing a basic description of the object.
/v1/query
Mount Point: /mn/v1/query
GET
Response Body
| element: | (custom) |
| media types: | application/xml |
(no documentation provided)
/v1/query/{queryEngine}/{query}
Mount Point: /mn/v1/query/{queryEngine}/{query}
GET
Submit a query against the specified queryEngine and return the response as formatted by the queryEngine. The MNQuery.query() operation may be implemented by more than one type of search engine and the queryEngine parameter indicates which search engine is targeted. The value and form of query is determined by the specific query engine. For example, the SOLR search engine will accept many of the standard parameters of SOLR, including field restrictions and faceting. This method is optional for Member Nodes, but if implemented, both getQueryEngineDescription and listQueryEngines must also be implemented.
Parameters
| name | description | type | default |
|---|---|---|---|
| queryEngine | specify the engine will be used for this query | path | |
| query | query string. | path |
Response Body
| element: | (custom) |
| media types: | application/xml |
Jersey Response Object, including the list of objects return from query engine.
/v1/query/{queryType}
Mount Point: /mn/v1/query/{queryType}
GET
Parameters
| name | description | type | default |
|---|---|---|---|
| queryType | (no documentation provided) | path |
Response Body
| element: | (custom) |
| media types: | application/xml |
(no documentation provided)
/v1/replica/{pid}
Mount Point: /mn/v1/replica/{pid}
GET
Called by a target Member Node to fullfill the replication request originated by a Coordinating Node calling MNReplication.replicate(). This is a request to make a replica copy of the object, and differs from a call to GET /object in that it should be logged as a replication event rather than a read event on that object. If the object being retrieved is restricted access, then a Tier 2 or higher Member Node MUST make a call to CNReplication.isNodeAuthorized() to verify that the Subject of the caller is authorized to retrieve the content. A successful operation is indicated by a HTTP status of 200 on the response. Failure of the operation MUST be indicated by returning an appropriate exception. Use Cases: UC09 Rest URL: GET /replica/{pid}
Parameters
| name | description | type | default |
|---|---|---|---|
| pid | pid (Types.Identifier) – The identifier of the object to get as a replica Transmitted as part of the URL path and must be escaped accordingly. | path |
Response Body
| element: | (custom) |
| media types: | */* application/xml application/json |
Types.OctetStream Bytes of the specified object.