-
Notifications
You must be signed in to change notification settings - Fork 1
/
Copy pathdraft-ietf-netconf-list-pagination-rc.xml
486 lines (437 loc) · 22.1 KB
/
draft-ietf-netconf-list-pagination-rc.xml
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
393
394
395
396
397
398
399
400
401
402
403
404
405
406
407
408
409
410
411
412
413
414
415
416
417
418
419
420
421
422
423
424
425
426
427
428
429
430
431
432
433
434
435
436
437
438
439
440
441
442
443
444
445
446
447
448
449
450
451
452
453
454
455
456
457
458
459
460
461
462
463
464
465
466
467
468
469
470
471
472
473
474
475
476
477
478
479
480
481
482
483
484
485
486
<?xml version='1.0' encoding='utf-8'?>
<!DOCTYPE rfc
[
<!ENTITY nbsp " ">
<!ENTITY zwsp "​">
<!ENTITY nbhy "‑">
<!ENTITY wj "⁠">
]>
<?xml-stylesheet type="text/xsl" href="rfc2629.xslt"?>
<?rfc toc="yes"?>
<?rfc compact="no"?>
<?rfc subcompact="no"?>
<?rfc iprnotified="no"?>
<?rfc strict="yes"?>
<?rfc-ext allow-markup-in-artwork="yes" ?>
<?rfc-ext include-index="no" ?>
<rfc xmlns:xi="http://www.w3.org/2001/XInclude"
submissionType="IETF"
docName="draft-ietf-netconf-list-pagination-rc-latest"
category="std"
consensus="true"
ipr="trust200902"
updates="8040">
<front>
<title abbrev="RESTCONF Pagination Support">
RESTCONF Extensions to Support List Pagination
</title>
<author fullname="Kent Watsen" initials="K." surname="Watsen">
<organization>Watsen Networks</organization>
<address>
<email>[email protected]</email>
</address>
</author>
<author fullname="Qin Wu" initials="Q." surname="Wu">
<organization>Huawei Technologies</organization>
<address>
<email>[email protected]</email>
</address>
</author>
<author fullname="Per Andersson" initials="P." surname="Andersson">
<organization>Cisco Systems</organization>
<address>
<email>[email protected]</email>
</address>
</author>
<author fullname="Olof Hagsand" initials="O." surname="Hagsand">
<organization>SUNET</organization>
<address>
<email>[email protected]</email>
</address>
</author>
<author fullname="Hongwei Li" initials="H." surname="Li">
<organization>Hewlett Packard Enterprise</organization>
<address>
<email>[email protected]</email>
</address>
</author>
<date/>
<area>OPS Area</area>
<workgroup>NETCONF Working Group</workgroup>
<abstract>
<t>This document defines a mapping of the list pagination mechanism
defined in <xref target="I-D.ietf-netconf-list-pagination"/>
to RESTCONF <xref target="RFC8040"/>.</t>
<t>This document updates RFC 8040, to declare "list" and "leaf-list" as
valid resource targets for the RESTCONF GET and DELETE
operations, to define GET query parameters necessary
for list pagination, and to define a media-type for
XML-based lists.</t>
</abstract>
</front>
<middle>
<section anchor="intro" title="Introduction">
<t>This document defines a mapping of the list pagination mechanism
defined in <xref target="I-D.ietf-netconf-list-pagination"/>
to RESTCONF <xref target="RFC8040"/>.</t>
<t>This document updates RFC 8040, as described in <xref target="updates"/>.</t>
<t>Declaring "list" and "leaf-list" as valid resource targets
for the GET operation is necessary for list pagination. Declaring
these nodes as valid resource targets for the DELETE operation
merely completes the solution for RESTCONF.</t>
<section title="Terminology">
<t>The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL
NOT", "SHOULD", "SHOULD NOT", "RECOMMENDED", "NOT RECOMMENDED",
"MAY", and "OPTIONAL" in this document are to be interpreted as
described in BCP 14 <xref target="RFC2119"/> <xref target="RFC8174"/>
when, and only when, they appear in all capitals, as shown here.</t>
</section>
<section title="Conventions">
<t>Various examples in this document use "BASE64VALUE=" as a
placeholder value for binary data that has been base64
encoded (per <xref section="9.8" target="RFC7950"/>). This
placeholder value is used because real base64 encoded structures
are often many lines long and hence distracting to the example
being presented.</t>
</section>
</section> <!-- intro -->
<section title="Updates to RFC 8040" anchor="updates">
<section title="Resource Targets">
<t>This document extends <relref section="3.5" target="RFC8040"/>
to add "list" and "leaf-list" nodes (not just their entries)
as valid data resources for the "GET" and "DELETE" operations.</t>
</section>
<section title="Media Type">
<t>This document extends <relref section="3.2" target="RFC8040"/>
to add a new media type, "application/yang-data+xml-list", to
encode "list" and "leaf-list" nodes in XML.</t>
<t>The "application/yang-data+xml-list" media-type defines a
pseudo top-level element called "xml-list" that is used to
wrap the response set, thus ensuring that a single top-level
element is returned for the XML encoding", as required by <relref
section="4.3" target="RFC8040"/>.</t>
<t>For JSON, the existing "application/yang-data+json" media type is
sufficient, as the JSON format has built-in support for encoding
arrays.</t>
<t>The "application/yang-data+xml-list" media type is registered
in <xref target="media-type"/>.</t>
</section>
<section title="Query Parameters">
<t>This document extends <relref section="4.8" target="RFC8040"/>
to add new query parameters "limit", "offset", "cursor", "direction",
"sort-by", "locale", "where", and "sublist-list".</t>
<t>These six query parameters correspond to those defined in
Sections 3.1 and 3.2 in <xref target="I-D.ietf-netconf-list-pagination"/>.</t>
<t>
<figure>
<artwork><![CDATA[
+---------------+---------+-----------------------------------------+
| Name | Methods | Description |
+---------------+---------+-----------------------------------------+
| limit | GET, | Limits the number of entries returned. |
| | HEAD | If not specified, the number of entries |
| | | that may be returned is unbounded. |
| | | |
| offset | GET, | Indicates the number of entries in the |
| | HEAD | result set that should the skipped over |
| | | when preparing the response. If not |
| | | specified, then no entries in the |
| | | result set are skipped. |
| | | |
| cursor | GET, | Indicates where to start the working |
| | HEAD | result set, the previous entries are |
| | | skipped over. If not specified, then |
| | | no entries in the result set are |
| | | skipped over. |
| | | |
| direction | GET, | Indicates the direction that the result |
| | HEAD | set is to be traversed. If not |
| | | specified, then the result set is |
| | | traversed in the "forwards" direction. |
| | | |
| sort-by | GET, | Indicates the node name that the result |
| | HEAD | set should be sorted by. If not |
| | | specified, then the result set's |
| | | default order is used, per YANG's |
| | | "ordered-by" statement. |
| | | |
| locale | GET, | Specifies the locale the server should |
| | HEAD | use when collating the result set. If |
| | | not specified, the server chooses what |
| | | locale is used for collation. |
| | | |
| where | GET, | Specifies a filter expression that |
| | HEAD | result set entries must match. If |
| | | not specified, then no entries are |
| | | filtered from the result set. |
| | | |
| sublist-limit | GET, | Limits the number of entries returned |
| | HEAD | returned for descendent lists and |
| | | leaf-lists. If not specified, the |
| | | number of entries that may be returned |
| | | is unbounded. |
+---------------+---------+-----------------------------------------+
]]></artwork>
</figure>
</t>
<t>For all of the query parameters, the query parameter is only
allowed for the GET and HEAD methods on "list" and "leaf-list"
data resources. A "400 Bad Request" status-line MUST be returned
if used with any other method or resource type. The error-tag
value "operation-not-supported" is used in this case.</t>
<t>Per the conformance defined in <relref section="3.1"
target="I-D.ietf-netconf-list-pagination"/>,
all of these parameters MUST be supported for all lists and
leaf-lists, but servers MAY disable the support for some or all
"config false" lists, as described in <relref section="3.3"
target="I-D.ietf-netconf-list-pagination"/>.</t>
<section title='The "limit" Query Parameter'>
<t>The "limit" query parameter corresponds to the "limit"
parameter defined in <relref section="3.1.7"
target="I-D.ietf-netconf-list-pagination"/>.</t>
<t>If the limit value is invalid, then a "400 Bad Request"
status-line MUST be returned with the error-type value
"application" and error-tag value "invalid-value".</t>
</section>
<section title='The "offset" Query Parameter'>
<t>The "offset" query parameter corresponds to the "offset"
parameter defined in <relref section="3.1.5"
target="I-D.ietf-netconf-list-pagination"/>.</t>
<t>If the offset value is invalid, a "400 Bad Request" status-line
MUST be returned with the error-type value "application" and
error-tag value "invalid-value".</t>
<t>If the offset value exceeds the number of entries in the
working result set, then a "416 Range Not Satisfiable"
status-line MUST be returned with the error-type value
"application", error-tag value "invalid-value", and SHOULD also
include the "offset-out-of-range" identity as error-app-tag
value.</t>
</section>
<section title='The "cursor" Query Parameter'>
<t>The "cursor" querey parameter corresponds to the "cursor"
parameter defined in <relref section="3.1.6"
target="I-D.ietf-netconf-list-pagination"/>.</t>
<t>If the cursor value is unknown, i.e. the key does not exist,
a "404 Not Found" status-line MUST be returned with the error-type
value "application" and error-tag value "invalid-value", and SHOULD
also include the "cursor-not-found" identity as error-app-tag
value.</t>
<t>If the "cursor" query parameter is not supported on the target
node, then a a "501 Not Implemented" status-line MUST be returned
with error-type value "application" and error-tag value
"operation-not-supported".</t>
</section>
<section title='The "direction" Query Parameter'>
<t>The "direction" query parameter corresponds to the "direction"
parameter defined in <relref section="3.1.4"
target="I-D.ietf-netconf-list-pagination"/>.</t>
<t>If the direction value is invalid, then a "400 Bad Request"
status-line MUST be returned with the error-type value
"application" and error-tag value "invalid-value".</t>
</section>
<section title='The "sort-by" Query Parameter'>
<t>The "sort-by" query parameter corresponds to the "sort-by"
parameter defined in <relref section="3.1.2"
target="I-D.ietf-netconf-list-pagination"/>.</t>
<t>If the specified node identifier is invalid, then a "400 Bad
Request" status-line MUST be returned with the error-type value
"application" and error-tag value "invalid-value".</t>
</section>
<section title='The "locale" Query Parameter'>
<t>The "locale" query parameter corresponds to the
"locale" parameter defined in <relref section="3.1.3"
target="I-D.ietf-netconf-list-pagination"/>.</t>
<t>If the specified node identifier is invalid, i.e. the locale is
unknown to the server, then a "501 Not Implemented" status-line
MUST be returned with the error-type value "application" and
error-tag value "invalid-value", and SHOULD also include the
"locale-unavailable" identity in as the error-app-tag value.</t>
<t>If "locale" is supplied but not "sort-by", a "400 Bad Request"
status-line MUST be return with the error-type "application" and
error-tag value "invalid-value".</t>
</section>
<section title='The "where" Query Parameter'>
<t>The "where" query parameter corresponds to the "where"
parameter defined in <relref section="3.1.1"
target="I-D.ietf-netconf-list-pagination"/>.</t>
<t>Prefixes in the XPath expression MUST be YANG module names.</t>
<t>If the specified XPath expression is invalid, then a "400 Bad
Request" status-line MUST be returned with the error-type value
"application" and error-tag value "invalid-value".</t>
</section>
<section title='The "sublist-limit" Query Parameter'>
<t>The "sublist-limit" query parameter corresponds to the
"sublist-limit" parameter defined in <relref section="3.2.1"
target="I-D.ietf-netconf-list-pagination"/>.</t>
<t>If the sumlist-limit value is invalid, then a "400 Bad Request"
status-line MUST be returned with the error-type value
"application" and error-tag value "invalid-value".</t>
</section>
</section>
</section> <!-- Updates to RFC 8040 -->
<section title="IANA Considerations">
<section title='The "RESTCONF Capability URNs" Registry'>
<t>This document registers six capabilities in the RESTCONF
Capability URNs <xref target="RFC8040"/> maintained at
<eref target="https://www.iana.org/assignments/restconf-capability-urns/restconf-capability-urns.xhtml"/>.
Following the instructions defined in <relref section="11.4" target="RFC8040"/>,
the below registrations are requested:</t>
<t>All the registrations are to use this document (RFC XXXX)
for the "Reference" value.</t>
<t>
<figure>
<artwork><![CDATA[
Index Capability Identifier
--------------------------------------------------------------------
:limit urn:ietf:params:restconf:capability:limit:1.0
:offset urn:ietf:params:restconf:capability:offset:1.0
:cursor urn:ietf:params:restconf:capability:cursor:1.0
:direction urn:ietf:params:restconf:capability:direction:1.0
:sort-by urn:ietf:params:restconf:capability:sort-by:1.0
:locale urn:ietf:params:restconf:capability:locale:1.0
:where urn:ietf:params:restconf:capability:where:1.0
:sublist-limit urn:ietf:params:restconf:capability:sublist-limit:1.0
]]></artwork>
</figure>
</t>
</section>
<section title='The "Media Types" Registry'>
<t>This document registers one media type in the "application"
subregistry of the Media Types registry <xref target="RFC6838"/>
<xref target="RFC4855"/> maintained at <eref target="https://www.iana.org/assignments/media-types/media-types.xhtml#application"/>.
Following the format defined in <xref target="RFC4855"/>, the below
registration is requested:</t>
<section title='Media Type "application/yang-data+xml-list"' anchor="media-type">
<figure>
<artwork>Type name: application
Subtype name: yang-data+xml-list
Required parameters: None
Optional parameters: None
Encoding considerations: 8-bit
Each conceptual YANG data node is encoded according to the
XML Encoding Rules and Canonical Format for the specific
YANG data node type defined in [RFC7950].
Security considerations: Security considerations related
to the generation and consumption of RESTCONF messages
are discussed in Section 12 of RFC 8040. Additional
security considerations are specific to the semantics
of particular YANG data models. Each YANG module is
expected to specify security considerations for the
YANG data defined in that module.
Interoperability considerations: RFC XXXX specifies the
format of conforming messages and the interpretation
thereof.
Published specification: RFC XXXX
Applications that use this media type: Instance document data
parsers used within a protocol or automation tool that
utilize the YANG Patch data structure.
Fragment identifier considerations: Fragment identifiers for
this type are not defined. All YANG data nodes are
accessible as resources using the path in the request URI.
Additional information:
Deprecated alias names for this type: N/A
Magic number(s): N/A
File extension(s): None
Macintosh file type code(s): "TEXT"
Person & email address to contact for further information:
See the Authors' Addresses section of RFC XXXX.
Intended usage: COMMON
Restrictions on usage: N/A
Author: See the Authors' Addresses section of RFC XXXX.
Change controller: Internet Engineering Task Force
(mailto:[email protected]).
Provisional registration? (standards tree only): no
</artwork>
</figure>
</section>
</section>
</section>
<section anchor="security" title="Security Considerations">
<t>This document introduces protocol operations for paging
through data already provided by the RESTCONF protocol, and
hence does not introduce any new security considerations.</t>
<t>This document does not define a YANG module and hence there
are no data modeling considerations beyond those discussed in
<xref target="I-D.ietf-netconf-list-pagination"/>.</t>
</section>
</middle>
<back>
<references title="Normative References">
<xi:include href="https://bib.ietf.org/public/rfc/bibxml/reference.RFC.2119.xml"/> <!-- Terms -->
<xi:include href="https://bib.ietf.org/public/rfc/bibxml/reference.RFC.8040.xml"/> <!-- RESTCONF -->
<xi:include href="https://bib.ietf.org/public/rfc/bibxml/reference.RFC.8174.xml"/> <!-- Terms new -->
<xi:include href="https://xml2rfc.ietf.org/public/rfc/bibxml3/reference.I-D.ietf-netconf-list-pagination.xml"/>
</references>
<references title="Informative References">
<xi:include href="https://bib.ietf.org/public/rfc/bibxml/reference.RFC.4855.xml"/> <!-- ??? -->
<xi:include href="https://bib.ietf.org/public/rfc/bibxml/reference.RFC.6838.xml"/> <!-- ??? -->
<xi:include href="https://bib.ietf.org/public/rfc/bibxml/reference.RFC.7950.xml"/> <!-- ??? -->
<xi:include href="https://xml2rfc.ietf.org/public/rfc/bibxml3/reference.I-D.ietf-netconf-restconf-collection.xml"/>
</references>
<section title="Example YANG Module">
<t>The examples within this document use the "example-social" YANG
module defined in <relref section="A.1" target="I-D.ietf-netconf-list-pagination"/>.</t>
</section>
<section title="Example Data Set">
<t>The Example Data Set used by the examples is defined in
<relref section="A.2" target="I-D.ietf-netconf-list-pagination"/>.</t>
</section>
<section title="Example Queries">
<section title='List pagination with all query parameters'>
<t>This example mimics that <relref section="A.3.9" target="I-D.ietf-netconf-list-pagination"/>.
This example is presented twice, once using XML and again using JSON.</t>
<t>XML:
<figure><artwork><![CDATA[
INSERT_TEXT_FROM_FILE(includes/ex-api-combo-rpc.xml)
]]></artwork></figure>
</t>
<t>Response from the RESTCONF server:
<figure><artwork><![CDATA[
INSERT_TEXT_FROM_FILE(includes/ex-api-combo-rpc-reply.xml)
]]></artwork></figure>
</t>
<t>JSON:
<figure><artwork><![CDATA[
INSERT_TEXT_FROM_FILE(includes/ex-api-combo-rpc.json)
]]></artwork></figure>
</t>
<t>Response from the RESTCONF server:
<figure><artwork><![CDATA[
INSERT_TEXT_FROM_FILE(includes/ex-api-combo-rpc-reply.json)
]]></artwork></figure>
</t>
</section>
<section title='Deletion of a leaf-list'>
<t>This example illustrates using a "leaf-list" as the DELETE target.
<figure><artwork><![CDATA[
INSERT_TEXT_FROM_FILE(includes/ex-api-delete-rpc.xml)
]]></artwork></figure>
</t>
<t>Response from the RESTCONF server:
<figure><artwork><![CDATA[
INSERT_TEXT_FROM_FILE(includes/ex-api-delete-rpc-reply.xml)
]]></artwork></figure>
</t>
</section>
</section> <!-- Example Queries -->
<!--
<section title="Contributors" numbered="no">
<figure>
<artwork>David Cornejo
[email protected]</artwork>
</figure>
</section>
-->
<section title="Acknowledgements" numbered="no">
<t>This work has benefited from the discussions of restconf resource
collection over the years, in particular,
<xref target="I-D.ietf-netconf-restconf-collection"/>. The
authors additionally thank the following for lively discussions on
list (ordered by first name):
Andy Bierman,
Martin Björklund,
and Robert Varga
</t>
</section>
</back>
</rfc>