Skip to content

Commit e4ffb67

Browse files
datadavevdatadavev
committed
Refactored CN API for new generator and autosummary
1 parent 1c2e677 commit e4ffb67

33 files changed

+628
-3214
lines changed

‎MethodCrossReference.xls

-1.5 KB
Binary file not shown.

‎source/apis/CN_APIs.txt

+91-43
Original file line numberDiff line numberDiff line change
@@ -1,18 +1,31 @@
1+
.. include:: api_substitutions.txt
2+
13
Coordinating Node APIs
24
----------------------
35

6+
.. contents::
7+
:local:
8+
:depth: 1
9+
10+
411
The service interfaces described here are exposed through the Coordinating
512
Node REST interface to support interactions with Member Nodes and DataONE
613
clients.
714

15+
**CNDiagnostic Methods**
16+
17+
.. autofuncsummary:: CNDiagnostic
18+
:functions:
19+
20+
821
The following table provides a list of API methods exposed by Coordinating
922
Nodes.
1023

11-
:Tier:
24+
:Tier:
1225

1326
The tier in which a method is grouped.
1427

15-
:Version:
28+
:Version:
1629

1730
Version of API method is available. The lowest version number indicates when
1831
the method was added. A version number in parentheses indicates the method is
@@ -24,7 +37,7 @@ Nodes.
2437
:REST:
2538

2639
The HTTP method and path relative to the Base URL. Parameters specified in the
27-
URL are indicatd by braces. Note that parameters included in a path MUST be
40+
URL are indicated by braces. Note that parameters included in a path MUST be
2841
properly path encoded, and parameters included as key, value pairs MUST also
2942
be properly encoded.
3043

@@ -44,82 +57,114 @@ Nodes.
4457
Diagnostic API
4558
~~~~~~~~~~~~~~
4659

47-
.. module:: CNDiagnostic
48-
:synopsis: Operations to assist with diagnosing authentication and content
49-
formatting.
60+
|CN| operations to assist clients with diagnosing authentication and content formatting.
61+
62+
.. autofuncsummary:: CNDiagnostic
63+
:functions:
64+
65+
.. automodule:: CNDiagnostic
66+
:members:
67+
:undoc-members:
68+
:show-inheritance:
5069

51-
.. include:: generated/generated_CNDiagnostic.txt
5270

5371

5472
Core API
5573
~~~~~~~~
5674

57-
.. module:: CNCore
58-
:synopsis: Core operations necessary for basic interaction with
59-
Coordinating Nodes
75+
Core operations necessary for basic interaction with |CN|s.
76+
77+
.. autofuncsummary:: CNCore
78+
:functions:
6079

61-
.. include:: generated/generated_CNCore.txt
80+
.. automodule:: CNCore
81+
:members:
82+
:undoc-members:
83+
:show-inheritance:
6284

6385

6486
Read API
6587
~~~~~~~~
6688

67-
.. module:: CNRead
68-
:synopsis: Data read operations for Coordinating Nodes
69-
70-
The *CN_read* API implements methods that enable object retrieval operations
71-
on a :term:`Coordinating Node`. It includes searches of science metadata and
89+
The *CNRead* API implements methods that enable object retrieval operations
90+
on a |CN|. It includes searches of science metadata and
7291
system metadata and exposes log records held by CNs.
7392

74-
.. include:: generated/generated_CNRead.txt
93+
.. autofuncsummary:: CNRead
94+
:functions:
95+
96+
.. automodule:: CNRead
97+
:members:
98+
:undoc-members:
99+
:show-inheritance:
75100

76101
View API
77102
~~~~~~~~
78103

79-
.. module:: CNView
80-
:synopsis: View operations to see formatted versions of metadata and data for Coordinating Nodes
104+
View operations to see formatted versions of metadata and data for CNs.
105+
106+
The *CNView* API implements methods that enable viewing content
107+
on a |CN|. Like the MNView service, the CNView service
108+
provides a transformed view of a metadata file, data file, or package. The
109+
CNView service provides a default view for all content, and may choose to
110+
redirect a review request to the authoritative Member Node for a given PID.
81111

82-
The *CNView* API implements methods that enable viewing content
83-
on a :term:`Coordinating Node`. Like the MNView service, the CNView service provides a transformed view of a metadata file, data file, or package. The CNView service provides a default view for all content, and may choose to redirect a review request to the authoritative Member Node for a given PID.
112+
.. autofuncsummary:: CNView
113+
:functions:
84114

85-
.. include:: generated/generated_CNView.txt
115+
.. automodule:: CNView
116+
:members:
117+
:undoc-members:
118+
:show-inheritance:
86119

87120

88121
Authorization API
89122
~~~~~~~~~~~~~~~~~
90123

91-
.. module:: CNAuthorization
92-
:synopsis: Methods for authorization and access control
124+
Methods for authorization and access control.
93125

94-
.. include:: generated/generated_CNAuthorization.txt
126+
.. autofuncsummary:: CNAuthorization
127+
:functions:
95128

129+
.. automodule:: CNAuthorization
130+
:members:
131+
:undoc-members:
132+
:show-inheritance:
96133

97134
Identity API
98135
~~~~~~~~~~~~
99136

100-
.. module:: CNIdentity
101-
:synopsis: Methods for account management and identity mapping.
137+
Methods for account management and identity mapping.
102138

103-
.. include:: generated/generated_CNIdentity.txt
139+
.. autofuncsummary:: CNIdentity
140+
:functions:
141+
142+
.. automodule:: CNIdentity
143+
:members:
144+
:undoc-members:
145+
:show-inheritance:
104146

105147

106148
Replication API
107149
~~~~~~~~~~~~~~~
108150

109-
.. module:: CNReplication
110-
:synopsis:
111-
Supports operations for replication of content between Member Nodes.
112-
151+
Supports operations for replication of content between Member Nodes.
113152

114153
The Data Replication API operates in conjunction with the
115154
:mod:`MNReplication` API to assist with the replication of data and
116155
science metadata content between Member Nodes to ensure that copies of data
117156
and metadata can be retrieved from more than one Member Node where possible.
118157

119-
.. include:: generated/generated_CNReplication.txt
158+
.. autofuncsummary:: CNReplication
159+
:functions:
160+
161+
.. automodule:: CNReplication
162+
:members:
163+
:undoc-members:
164+
:show-inheritance:
120165

121166
..
122-
167+
123168
This old stuff is commented out but kept here for revisiting later
124169
.. function:: getDefaultReplicationPolicy (sess)
125170

@@ -140,8 +185,7 @@ and metadata can be retrieved from more than one Member Node where possible.
140185
Register API
141186
~~~~~~~~~~~~
142187

143-
.. module:: CNRegister
144-
:synopsis: Register nodes and their capabilities, retrieve node list
188+
Register nodes and their capabilities, retrieve node list.
145189

146190
The register API methods are used to maintain a registry of nodes participating
147191
in the DataONE infrastructure.
@@ -154,8 +198,13 @@ implementing a parallel data store. In this case, the "science metadata" could
154198
be a DC description of the node, and the "data" might be the detailed
155199
registration information including node capabilities, scheduling and so forth.
156200

201+
.. autofuncsummary:: CNRegister
202+
:functions:
157203

158-
.. include:: generated/generated_CNRegister.txt
204+
.. automodule:: CNRegister
205+
:members:
206+
:undoc-members:
207+
:show-inheritance:
159208

160209

161210
..
@@ -168,7 +217,7 @@ registration information including node capabilities, scheduling and so forth.
168217

169218
:param nodeID: A PID that identifies the Member Node.
170219

171-
:param capabilities:
220+
:param capabilities:
172221
A capabilities document that describes the resources and supported
173222
services of the Member Node.
174223

@@ -207,11 +256,10 @@ registration information including node capabilities, scheduling and so forth.
207256
interaction with the MN as various aspects are evaluated.
208257

209258

210-
.. todo::
259+
.. todo::
211260
The :func:`verifyCapabilities` will need to check functionality of the MN so
212261
need to define a few service hooks for checking these properties.
213262

214-
215263
State of Health API
216264
~~~~~~~~~~~~~~~~~~~
217265

@@ -221,7 +269,7 @@ registration information including node capabilities, scheduling and so forth.
221269
.. module:: CN_health
222270
:synopsis: Methods for reporting on the state of health of a CN and on the entire DataONE infrastructure
223271

224-
::
272+
::
225273

226274
generateReport(token) -> statusReport
227275

@@ -241,15 +289,15 @@ registration information including node capabilities, scheduling and so forth.
241289
informatio returned is used to give administrators information necessary to
242290
maintain the infrastructure.
243291

244-
.. note::
292+
.. note::
245293
This method is used by Use Case 10 "MN Status Reports" for V0.3. However
246294
instead of a complete set of detailed status reports, the V0.3
247295
implementation of the use case will utilize the ``MN_health.heartbeat()``
248296
method to compile very basic information about the MNs. Later versions of
249297
this method will use the richer ``MN_health.getStatus(token)`` method.
250298

251299
:param token: Identity with authority to generate reports.
252-
300+
253301
:rtype: Status report, ideally in XML + stylsheet or at least XHTML.
254302

255303

‎source/apis/api_substitutions.txt

+6
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,6 @@
1+
.. |session| replace:: Session information that contains the identity of the
2+
calling user as retrieved from the X.509 certificate. Transmitted as part of
3+
the SSL handshake process.
4+
5+
.. |cnprivate| replace:: **Note:** This method is private to the CNs and is not available on the public API.
6+

‎source/apis/examples/cn_getFormat.txt

+7-13
Original file line numberDiff line numberDiff line change
@@ -1,27 +1,21 @@
11
**Example**
22

3-
Retrieve information about the ``http://www.openarchives.org/ore/terms``
3+
Retrieve information about the ``http://www.openarchives.org/ore/terms``
44
formatId. Note that formatId has characters that should be escaped when added
5-
as a URL path element. This is done using the urlencode script.
5+
as a URL path element. This is done here using a urlencode script.
66

7-
.. Note:: The *xml* command is implemented by XMLStarlet_, and is used here to
8-
format the output for easier reading. The *urlencode* command is a
9-
script available with the `d1_client_bash`_ itk tool
10-
117
.. code-block:: bash
8+
:linenos:
129

13-
formatid=$(echo "http://www.openarchives.org/ore/terms" | urlencode)
14-
curl -s "http://cn-dev.dataone.org/cn/v1/formats/${formatid}" | xml fo
10+
FORMATID=$(echo "http://www.openarchives.org/ore/terms" | urlencode)
11+
#encoded formatid: http%3A%2F%2Fwww.openarchives.org%2Fore%2Fterms
12+
13+
curl -s "https://cn.dataone.org/cn/v2/formats/${FORMATID}" | xml fo
1514

1615
<?xml version="1.0" encoding="UTF-8"?>
1716
<d1:objectFormat xmlns:d1="http://ns.dataone.org/service/types/v1">
1817
<formatId>http://www.openarchives.org/ore/terms</formatId>
1918
<formatName>Object Reuse and Exchange Vocabulary</formatName>
2019
<formatType>RESOURCE</formatType>
2120
</d1:objectFormat>
22-
23-
24-
.. _XMLStarlet: http://xmlstar.sourceforge.net/
25-
26-
.. _d1_client_bash: https://repository.dataone.org/software/cicore/trunk/itk/d1_client_bash
2721

‎source/apis/examples/cn_listObjectFormats.txt

+30-22
Original file line numberDiff line numberDiff line change
@@ -1,26 +1,34 @@
11
**Example**
22

3-
.. code-block:: bash
3+
.. code-block:: xml
4+
:linenos:
45

5-
curl "http://cn.dataone.org/cn/v1/formats"
6+
curl -s "http://cn.dataone.org/cn/v2/formats"
67

7-
<?xml version="1.0" encoding="UTF-8"?>
8-
<?xml-stylesheet type="text/xsl" href="/cn/xslt/dataone.types.v1.xsl"?>
9-
<d1:objectFormatList xmlns:d1="http://ns.dataone.org/service/types/v1" count="67" start="0" total="67">
10-
<objectFormat>
11-
<formatId>-//ecoinformatics.org//eml-access-2.0.0beta4//EN</formatId>
12-
<formatName>Ecological Metadata Language, Access module, version 2.0.0beta4</formatName>
13-
<formatType>METADATA</formatType>
14-
</objectFormat>
15-
<objectFormat>
16-
<formatId>-//ecoinformatics.org//eml-attribute-2.0.0beta4//EN</formatId>
17-
<formatName>Ecological Metadata Language, Attribute module, version 2.0.0beta4</formatName>
18-
<formatType>METADATA</formatType>
19-
</objectFormat>
20-
<objectFormat>
21-
<formatId>-//ecoinformatics.org//eml-constraint-2.0.0beta4//EN</formatId>
22-
<formatName>Ecological Metadata Language, Constraint module, version 2.0.0beta4</formatName>
23-
<formatType>METADATA</formatType>
24-
</objectFormat>
25-
...
26-
</d1:objectFormatList>
8+
<?xml version="1.0" encoding="UTF-8" standalone="yes"?><?xml-stylesheet type="text/xsl" href="/cn/xslt/dataone.types.v2.xsl" ?>
9+
<ns3:objectFormatList xmlns:ns2="http://ns.dataone.org/service/types/v1"
10+
xmlns:ns3="http://ns.dataone.org/service/types/v2.0"
11+
count="132" start="0" total="132">
12+
<objectFormat>
13+
<formatId>eml://ecoinformatics.org/eml-2.0.0</formatId>
14+
<formatName>Ecological Metadata Language, version 2.0.0</formatName>
15+
<formatType>METADATA</formatType>
16+
<mediaType name="text/xml"/>
17+
<extension>xml</extension>
18+
</objectFormat>
19+
<objectFormat>
20+
<formatId>eml://ecoinformatics.org/eml-2.0.1</formatId>
21+
<formatName>Ecological Metadata Language, version 2.0.1</formatName>
22+
<formatType>METADATA</formatType>
23+
<mediaType name="text/xml"/>
24+
<extension>xml</extension>
25+
</objectFormat>
26+
<objectFormat>
27+
<formatId>eml://ecoinformatics.org/eml-2.1.0</formatId>
28+
<formatName>Ecological Metadata Language, version 2.1.0</formatName>
29+
<formatType>METADATA</formatType>
30+
<mediaType name="text/xml"/>
31+
<extension>xml</extension>
32+
</objectFormat>
33+
...
34+
</ns3:objectFormatList>

0 commit comments

Comments
 (0)