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

From: Rodney Cummings <[email-masked]>
Date: Mon, 11 Jan 2016 22:30:26 +0000

Hello,

I have read and reviewed the restconf-09 document and my comments are below. I have no major objections to the content, and I support its publication. My affiliated company has definitive plans for a JSON-only server implementation in the future, and we are considering a client implementation.

Questions/concerns:
---

- Section 3.4.1.1: This section has "SHOULD maintain last-modified timestamps for descendant resources", and section 3.5 (data resource) has "the server MAY maintain a last-modified timestamp for the resource". I assume that a descendant resource is a data resource, so the MAY/SHOULD are somewhat contradictory. One solution would be to remove the conformance requirement for descendants from 3.4.1.1, and change 3.5 to a SHOULD. The same issue applies to entity tag.

- Section 3.7: Since support for YANG module retrieval is optional, should we provide a capability for it?

- Section 4.8.1: This has "The default value is determined by the "config" statement value of the requested data nodes." What if the requested data node is a container with a mixture of "config false" leafs and "config true" leafs? It seems like this could be replaced with "The default value is "all"."

- Sections 4.8.4 and 4.8.5: What if my server only supports modules that use the default ordering exclusively (system order)? If so, mandating "insert" and "point" is cumbersome. I tend to think that these should be grouped into a capability like other query parameters. If there is concern about this, we could state that "If the server implements a module with data nodes that specify user ordering, then the server MUST support this capability."

Typos/nits:
---

- Section 3, last paragraph: The first sentence states "The RESTCONF protocol does not include a resource discovery mechanism.", but the next section 3.1 specifies a resource discovery mechanism for the root. I know what you mean (i.e. RESTCONF doesn't discover YANG data nodes), but this threw me a bit when I first read it. For clarity I think you could remove this sentence, and the "Instead, " of the following sentence, and merge that that sentence into the preceding paragraph.

- Section 3.5.1: Change "If there are multiple key leaf values, the value of each leaf" to "If there are multiple key leaf values, the path segment is constructed by having the list name followed by an "=" followed by the leaf values. The value of each leaf". In other words, clarify that the "=" applies for both.

- Section 3.7: This has "The server can optionally support retrieval of the YANG modules it supports, using the "ietf-yang-library" module, defined in [I-D.ietf-netconf-yang-library]. To retrieve a YANG module, a client first needs to get the URL for retrieving the schema." On first read this sounds like ietf-yang-library is optional (which it isn't, Section 10). Another wording: "The server can optionally support retrieval of the YANG modules it supports. To retrieve a YANG module, a client first needs to get the URL for retrieving the schema using the "ietf-yang-library" module (Section 10)."

- Section 4: In "The PATCH method is equivalent to a "merge" operation when using a plain patch (see Section 4.6.1), other media-types may provide more granular control.", replace the comma with a semicolon.

- Section 4.4.1: In "The data-model for the child tree is the subtree is defined by YANG for the child resource.", replace the 2nd "is" with "as".

- Section 4.4.1: This has "The "insert" and "point" query parameters are supported by the POST method for datastore and data resource types, as specified in the YANG definition in Section 8.". The reference to Section 8 seems out of place. Should this be phrased like section 4.5 (PUT), with "The "insert" (Section 4.8.4) and "point" (Section 4.8.5) query parameters are supported by the POST method for for datastore and data resource types."?

- Section 5.3: In "If there was no request input, then the default output encoding is XML or JSON, depending or server preference.", replace the 2nd "or" with "on".

Rodney