Subject: [Netconf] Review of draft-ietf-netconf-restconf-09

From: Joe Clarke <[email-masked]>
Date: Fri, 8 Jan 2016 14:10:24 -0500

I wanted to give a review of my read-through of 
draft-ietf-netconf-restconf-09.  In general, I found no major issues, 
but the number of forward references was a bit distracting.  Below are 
my specific comments.

Section 2.1: It is stated that RESTCONF requires a secure transport 
layer.  It does not, however, explicitly state RESTCONF can or cannot be 
run over "http".  My assumption is, "no," but should this explicitly be 
stated?

Section 3.7: You provide an example of how to retrieve schema.  In the 
schema fetch case, you specify the HTTP headers the client might send, 
but you do not specify the headers the server will respond with.  This 
is out of sync with your other examples, and here I think the headers 
are important as it shows the content type.

Sections 4.X: Where it talks about authorization, it states that the 
server can either reply with 403 or 404.  I personally don't like this. 
  There is no guidance as to which to use where, and I think 403 should 
be used universally if there is an access issue.  It confuses a 
developer and could ultimately confuse an end-user if a 404 Not Found is 
returned for a a given target resource when it does, in fact, exist.

At the very least, I think some guidance should be offered about when to 
use which error code.

Section 4.8.9: I think the description for "explicit" is wrong here.  If 
you look further down the draft, the correct description is seen, which 
jives with the NETCONF definition.

OLD TEXT:

Data nodes set by the client are not reported

NEW TEXT:

Data nodes set to the YANG default by the client are reported

Section 5.1: Nit: Add a leading '/' for ".well-known"

OLD TEXT:

entry: the root of the RESTCONF API configured on this HTTP
server, discovered by getting the ".well-known/host-meta"
resource, as described in Section 3.1.

NEW TEXT:

entry: the root of the RESTCONF API configured on this HTTP
server, discovered by getting the "/.well-known/host-meta"
resource, as described in Section 3.1.

Section 7: Error code 404 is not mapped to anything, so going back to my 
comments about 403/404 above should we be suggesting one returns 404 for 
access denied?  Based on this, I think not.  I also assume 404 is not 
used for thinks like unknown-element as the NETCONF error-info for this 
points to bad-element?

Joe