Subject: Re: [Netconf] WG Last Call for draft-ietf-netconf-restconf-09, draft-ietf-netconf-yang-patch-07 and draft-ietf-netconf-yang-library-03

From: t.petch <[email-masked]>
Date: Wed, 20 Jan 2016 18:43:08 +0000

[um, got error messages so sending it again and again]

I have had a first look at netconf-restconf-09 up to the start of
section 4.  I have not been exposed to REST and its variants except on
the IETF lists, nor to HTTP 1.1, and so my comments are more editorial
than technical.  Mostly, this is about what I see as a thread running
through the I-D, on the use of terminology, which makes it more
difficult for me to understand than I would like.

s.1 " the user should not need any prior knowledge of NETCONF in order
to use RESTCONF."
Really? so why is RFC6241 a Normative reference:-)  Well, obviously you
do need an intimate knowledge of NETCONF else you get the kind of
discussions on the netmod wg list from those trying to understand YANG
without NETCONF:-)  I think you should say something like

" the user should not need any prior knowledge of the NETCONF protocol
in order to  use RESTCONF but does need to understand the concepts
defined in RFC6241 such as configuration, state and datastores"

s1.4 defines terminology much of which has been used or not used in the
previous sections.  I think that Terminology belongs before s.1.1

s1.4 defines configuration and state and the latter is then hardly ever
used (twice as far as I can see) whereas 'operational data' occurs over
and over again without AFAICT ever being defined.  Given the ongoing
discussions in netmod concerning operational state, I think this
problematicr.  Having defined 'state', then 'state' should be used (or
else wait for consensus on Derived State etc and then use them but that
might take a while:-); but see also s.3.3.1.

 s.1
"defined in NETCONF [RFC6241].

   The NETCONF protocol defines configuration datastores and ...
"

Um no; NETCONF (which you have just equated to RFC6241) defines
configuration datastores and ... so elide "The" and "protocol".

s.1 "RESTCONF uses HTTP operations to provide CRUD operations on a
NETCONF datastore "

The reference to NETCONF could confuse as to whether NETCONF is required
to use RESTCONF or not.  I assume from the Introduction that NETCONF is
not a prerequisite for RESTCONF but the rest of the document seems less
clear on this.  In particular, the discussion on what datastores get
updated when implies to me that NETCONF is there.  I think that this
needs clarifying.

Likewise, I think greater clarity is needed about datastores; can
RESTCONF access user-defined ones or only startup/candidate/running?
For me, s.1.3 comes at this from the wrong direction - assume the reader
understands datastores and their existence, because they must understand
that part of RFC6241, then what is the algorithm to decide which
datastore is accessed along the lines of'if  .. then  ... else if ...  '
I realise that this has evolved with the I-D but think that the current
text has become unclear.

RFC6241 is famously vague about this as we have discussed before so I
think that this needs to be more precise.

s.1 I note that the reference for XML is not that same as that used in
RFC6241 - is there a significant difference?

s.1.3 "The candidate is automatically committed to running after a
successful edit."
For interoperability, that sounds to me like the server 'MUST commit to
running'

s.1.4.3 "   o  RPC operation (now called protocol operation)"
um where so called?  I see RPC still in RFC6241 and rfc6020bis

s.2.2 "Consistent with the exclusive use of X.509v3 certificates for
NETCONF over TLS [RFC7589],  use of certificates in RESTCONF is also
limited to X.509v3 certificates."

I think that this is open to misinterpretation.  It is the use of TLS by
NETCONF that is limited to X.509v3 certificates, not that when TLS uses
certificates, as opposed to e.g. PSK, then they must be X.509v3.  I seem
to recall the IESG getting this wrong with call-home so best to be
precise.

s.2.5 "If the RESTCONF client is not authenticated to access a resource,
..
"
Well, no, it is not authorised, not not authenticated.

s.3 "top-level data node"
Again from netmod discussions, this term seems open to misunderstanding
and seems not to be defined.  I never quite know what is intended by it.

s.3.1 It is sort of unfortunate that the restconf API root in the
examples is always 'restconf'.  Doubtless, most servers will do this and
inevitably, some client will hardcode this and then fail on a server
that uses something else.  I think that you need to show that the API
root can be called 'rockandroll' or some other term of your choosing.

s.3.2 In a similar vein, a media type of  'application/yang.errors+xml '
corresponds to a resource of 'errors', just what I would expect, until a
media type of 'application/yang.operation+xml ' corresponds to
'operations'.  Another fruitful source of coding errors:-)

s.3.3.1 '?content=nonconfig  '

Unfortunate.  This makes it at least three in this I-D, 'state',
'operational configuration' and now 'nonconfig'.  Given the rumblings on
the netmod list, this could run and run.

s.3.5.2 "leaf has not been given a value"
default handling is another of those topics I see confusing those coming
to YANG without NETCONF.  Is this 'configured with a value'?  If so, I
suggest it be made explicit.

s.3.7 "The server can optionally support retrieval of the YANG modules
it
   supports, using the "ietf-yang-library" module, "

But s.1.2 says "The server lists each YANG module
   it supports using the "ietf-yang-library" YANG module, defined in
   [I-D.ietf-netconf-yang-library].  The server MUST implement the
   "ietf-yang-library" module, which MUST identify all the YANG modules
   used by the server."
so what is optional in s.3.7?

More to come:-(

Tom Petch

----- Original Message -----
From: <Ersue>; <Mehmet (Nokia - DE/Munich)>
To: "[email-masked]" <mailto:[email-masked]>
Cc: "[email-masked] ' >" <mailto:[email-masked]@ietf.org
<mailto:[email-masked]>; "[email-masked] ' >"
<mailto:[email-masked]@ietf.org <mailto:[email-masked]>;
"[email-masked] ' >" <mailto:[email-masked]@ietf.org
<mailto:[email-masked]>; "[email-masked] ' >"
<mailto:[email-masked]@ietf.org <mailto:[email-masked]>
Sent: Wednesday, January 20, 2016 5:04 PM

> Dear NETCONF WG,
> we hereby issue a WG Last Call for the drafts below:
> <http://tools.ietf.org/html/draft-ietf-netconf-restconf-09.txt>
> <http://tools.ietf.org/html/draft-ietf-netconf-yang-patch-07.txt>
> <http://tools.ietf.org/html/draft-ietf-netconf-yang-library-03.txt>
> Please review and send your comments to the NETCONF WG mailing list by
January 22, 2015 EOB PT.
> The drafts on RESTCONF, YANG patch and YANG library are planned to
publish as standard track documents.
> As RESTCONF is a major protocol we seek a detailed and thorough review
within NETCONF WG but also by the related WGs before publishing.
> Therefore the WGLC is planned to finalize on January 22th (covering
the holiday time in between) and APP, INT and RTG area ADs will be
informed as well as Core, I2RS, 6lo, and 6tisch WGs are invited to
review.
> Please take your time to review the documents and send your comments
to the NETCONF maillist by the deadline.
> Please state on NETCONF maillist also explicitly, whether you have
read/reviewed and whether you support the publication.
> Furthermore please indicate if you plan to implement or have already
implementations for RESTCONF and its supplementary drafts.
> Thank you for your review and kind help getting RESTCONF
specifications stable.
> Best Regards,
> Mehmet and Mahesh

---

From: Mahesh Jethanandani <[email-masked]>
Date: Sat, 23 Jan 2016 18:25:59 -0700

The Last Call period for the above three drafts closed yesterday. Thanks to everyone who provided comments on the three drafts.

The authors will update the documents based on the comments received and post an updated version of the draft(s).

Mahesh & Mehmet.

> On Dec 15, 2015, at 2:09 PM, Ersue, Mehmet (Nokia - DE/Munich) <[email-masked]> wrote:
> 
> FYI and attention.
>  
> Please provide your comments to NETCONF WG maillist.
>  
> Mehmet
>  
> From: Ersue, Mehmet (Nokia - DE/Munich) 
> Sent: Tuesday, December 15, 2015 9:59 PM
> To: [email-masked] <mailto:[email-masked]>
> Cc: [email-masked] <mailto:[email-masked]>' <[email-masked] <mailto:[email-masked]>>; [email-masked] <mailto:[email-masked]>' <[email-masked] <mailto:[email-masked]>>; [email-masked] <mailto:[email-masked]>' <[email-masked] <mailto:[email-masked]>>; [email-masked] <mailto:[email-masked]>' <[email-masked] <mailto:[email-masked]>>
> Subject: WG Last Call for draft-ietf-netconf-restconf-09, draft-ietf-netconf-yang-patch-07 and draft-ietf-netconf-yang-library-03
>  
> Dear NETCONF WG,
>  
> http://tools.ietf.org/html/draft-ietf-netconf-restconf-09.txt <http://tools.ietf.org/html/draft-ietf-netconf-restconf-09.txt>
> http://tools.ietf.org/html/draft-ietf-netconf-yang-patch-07.txt <http://tools.ietf.org/html/draft-ietf-netconf-yang-patch-07.txt>
> http://tools.ietf.org/html/draft-ietf-netconf-yang-library-03.txt <http://tools.ietf.org/html/draft-ietf-netconf-yang-library-03.txt>
>  
> Please review and send your comments to the NETCONF WG mailing list by January 22, 2015 EOB PT.
>  
> The drafts on RESTCONF, YANG patch and YANG library are planned to publish as standard track documents.
>  
> As RESTCONF is a major protocol we seek a detailed and thorough review within NETCONF WG but also by the related WGs before publishing.
> Therefore the WGLC is planned to finalize on January 22th (covering the holiday time in between) and APP, INT and RTG area ADs will be informed as well as Core, I2RS, 6lo, and 6tisch WGs are invited to review.
>  
> Please take your time to review the documents and send your comments to the NETCONF maillist by the deadline.
> Please state on NETCONF maillist also explicitly, whether you have read/reviewed and whether you support the publication.
> Furthermore please indicate if you plan to implement or have already implementations for RESTCONF and its supplementary drafts.
>  
> Thank you for your review and kind help getting RESTCONF specifications stable.
>  
> Best Regards,
> Mehmet and Mahesh

---

From: "Ersue, Mehmet (Nokia - DE/Munich)" <[email-masked]>
Date: Sun, 24 Jan 2016 21:14:29 +0000

Dear All,

Thank You all indeed for the thorough reviews. We've got many valuable comments.
I believe the RESTCONF drafts are on the right track and it'll be good to go to AD review after a careful update.

Below are a few points for draft-ietf-netconf-restconf-09 to emphasize some of the comments on the maillist and a few minor things to increase the clarity.
It is fine if the authors find a better formulation than I propose.

- Section 1.1:
"Edits are usually applied to one data resource instance at a time."
The word "usually" does not make it clear when this is the case.

- "The base RESTCONF protocol is intentionally simple to allow deployment for as many use cases as possible."
I agree with one of the reviewers that "as many use cases as" is not sufficiently clear.

- Section 1.1:
"simplified interface that follows REST principles"
In the abstract and NETCONF charter text we explicitly avoided to state that RESTCONF would be REST-based.
If we say it "follows REST principles"  we need to be very clear which principles are followed and which ones are not.

- Section 1.4.3:
I agree with one of the reviewers that the differentiation between RPC operation vs. protocol operation and the usage of these terms through the document is unclear.

- Section 1.4.4:
The abbreviation HATEOAS needs to be defined.
We need a reference to HTML5 (I think somebody stated this already).

- Section 2.4:
"The RESTCONF client MUST check the identity"
s/check/verify/
s/including processing the outcome as described in/
including processing the outcome of the identifier matching procedure as described in/
I think for readability we need to give at least a minimal hint for the type of the outcome.

- Section 2.5:
s/MUST either use TLS client certificates, like in NETCONF over TLS/
MUST either use TLS client certificates, as described in NETCONF over TLS/

s/scheme is also allowed, with the determination of how to process this combination
left as an implementation decision./
scheme is also allowed. The determination of how to process this combination
is seen as an implementation decision./

- Section 3.1:
s/In line with the best practices defined by [RFC7320<https://tools.ietf.org/html/rfc7320>],/
In line with the best practices for URI design defined in [RFC7320<https://tools.ietf.org/html/rfc7320>],/

s/the client MUST prepend it to any subsequent request/
the client MUST prefix it to any subsequent request/
I think this increases the readability for many non-native speakers.

Section 3.4.1.2:
s/the "ETag" ([RFC7232],<https://tools.ietf.org/html/rfc7232#section-2.3>   Section 2.3<https://tools.ietf.org/html/rfc7232#section-2.3>) header is returned/
the "ETag" header([RFC7232],<https://tools.ietf.org/html/rfc7232#section-2.3>   Section 2.3<https://tools.ietf.org/html/rfc7232#section-2.3>) is returned/
I think "ETag" header is one term.

Section 3.5.1:
s/double-quote is not a reserved characters/
double-quote is not a reserved character/

Section 3.5.2:
Suggest to rename the section title as: "3.5.2<https://tools.ietf.org/html/draft-ietf-netconf-restconf-09#section-3.5.2>.  Defaults Handling Mode"

s/default handling mode/
defaults handling mode/

Section 3.6:
s/if "module-A" defined a "reset-all" action/
if "module-A" defines a "reset-all" action/

Section 4:
s/Implementation of all methods (except PATCH) are defined in [RFC7231<https://tools.ietf.org/html/rfc7231>]./
HTTP methods and their semantics are defined in [RFC7231<https://tools.ietf.org/html/rfc7231>] except HTTP PATCH method is defined in [RFC5789<https://tools.ietf.org/html/rfc5789>]./

- In Section 4.3:
I agree with one of the reviewers that concerning "403 Forbidden" or "404 Not Found", GET should define which error response exactly should be used when.

Section 4.6:
s/Each patch type needs a unique media type./
Each patch type needs to use a unique media type./

Section 4.6.1:
s/Plain patch can used to/
Plain patch can be used to/

Section 4.8.9:
s/it MUST implement the behavior in Section 4.5.1 of [RFC6243]<https://tools.ietf.org/html/rfc6243#section-4.5.1>/
it MUST implement the behavior defined in Section 4.5.1 of [RFC6243]<https://tools.ietf.org/html/rfc6243#section-4.5.1>/

Section 5.3:
The sentence "This encoding is valid JSON, but also has special encoding rules to identify module namespaces and provide consistent type processing of YANG data." is unclear.
Does "This encoding" refer to the JSON encoding defined in [I-D.ietf-netmod-yang-metadata<https://tools.ietf.org/html/draft-ietf-netconf-restconf-09#ref-I-D.ietf-netmod-yang-metadata>]?
Why it is important to highlight that it is valid JSON?
I suggest to write "The JSON encoding defined in [I-D.ietf-netmod-yang-metadata<https://tools.ietf.org/html/draft-ietf-netconf-restconf-09#ref-I-D.ietf-netmod-yang-metadata>] has special encoding rules to identify module namespaces . . . "

Section 12:
s/Implementors/Implementers/

s/an authenticated NETCONF username be associated with/
an authenticated NETCONF username ([RFC 7589]) be associated with/

Section 13:
s/the The/The/

Mehmet

From: i2rs [mailto:[email-masked]] On Behalf Of EXT Mahesh Jethanandani
Sent: Sunday, January 24, 2016 2:26 AM
To: NETCONF <[email-masked]>
Cc: [email-masked]; [email-masked]; [email-masked]; [email-masked]; [email-masked]
Subject: Re: [i2rs] WG Last Call for draft-ietf-netconf-restconf-09, draft-ietf-netconf-yang-patch-07 and draft-ietf-netconf-yang-library-03

Mahesh & Mehmet.

On Dec 15, 2015, at 2:09 PM, Ersue, Mehmet (Nokia - DE/Munich) <[email-masked]<mailto:[email-masked]>> wrote:

FYI and attention.

Mehmet

From: Ersue, Mehmet (Nokia - DE/Munich)
Sent: Tuesday, December 15, 2015 9:59 PM
To: [email-masked]<mailto:[email-masked]>
Cc: [email-masked]<mailto:[email-masked]>' <[email-masked]<mailto:[email-masked]>>; [email-masked]<mailto:[email-masked]>' <[email-masked]<mailto:[email-masked]>>; [email-masked]<mailto:[email-masked]>' <[email-masked]<mailto:[email-masked]>>; [email-masked]<mailto:[email-masked]>' <[email-masked]<mailto:[email-masked]>>
Subject: WG Last Call for draft-ietf-netconf-restconf-09, draft-ietf-netconf-yang-patch-07 and draft-ietf-netconf-yang-library-03

Dear NETCONF WG,

http://tools.ietf.org/html/draft-ietf-netconf-restconf-09.txt
http://tools.ietf.org/html/draft-ietf-netconf-yang-patch-07.txt
http://tools.ietf.org/html/draft-ietf-netconf-yang-library-03.txt

Best Regards,
Mehmet and Mahesh