Subject: [Netconf] LL review of restconf-09

From: Ladislav Lhotka <[email-masked]>
Date: Mon, 11 Jan 2016 11:35:34 +0100

Hi,

I have read the document and my comments are below. Overall, I think the
document is in a good shape, and I support its publication. My company
is working on an open-source implementation.

Lada

*** General comments

    - RESTCONF separates the specification of the target node (in
      Request-URI) from new data (in the message body). This allows
      for a more flexible handling of lists and their entries, but I
      am not sure whether the following operations are permitted:
      1. DELETE an entire list by specifying it as the target
         resource;
      2. GET all list entries;
      3. create multiple list entries in one operation;
      4. change a list key (e.g. via PATCH), for example:

         PATCH /restconf/data/example-jukebox:jukebox/
             library/artist=Foo%20Fighters/album=Wasting%20Light HTTP/1.1
         Host: example.com
         If-Match: b8389233a4c
         Content-Type: application/yang.data+xml

         <album xmlns="http://example.com/ns/example-jukebox">
          <name>Something Else</name>
         </album>

*** Specific comments

**** Sec. 1
     - s/operational data/state data/ (also in several other places in
       the text).
     - JSON reference should be RFC 7159, 7158 is obsoleted by it.
**** Sec. 1.2
     - HATEOAS acronym should be expanded at the first occurence
**** Sec. 3.3.1
     - shouldn't the example have <jukebox> as the document element?
**** Sec. 3.5
     - first paragraph: leaf-list entries aren't data resources? And
       shouldn't it in fact be "Every instance of a container, ..."?
**** Sec. 3.5.1
     - 6th bullet: how can a key be missing?
**** Sec. 3.6
     - last two paragraphs: what does "successfully invoked" mean?
**** Sec. 3.7
     - It is a bit weird that the response has date "25 Apr 2012", but
       the returned revision is "2015-06-04".
**** Sec. 4
     - table: POST also corresponds to invoking an operation
**** Sec. 4.4.1
     - second paragraph: s/YANG definition/"ietf-restconf" module/
**** Sec. 4.5
     - What happens if the list key specified in the Request-URI isn't
       the same as the key specified in the message body?
**** Sec. 4.8.1
     - I don't understand what the default is: does "requested data
       nodes" mean the target resource? I would expect "all" to be the
       default.
**** Sec. 4.8.2
     - I don't understand how "depth" interacts with "fields": if
       "album" is the target resource, what is returned with
       "depth=1&fields=genre;year"?
**** Sec. 4.8.3
     - Is this legal: "fields=jukebox(library/artist;playlist)/name"?
**** Sec. 5.3 (also in 7.1)
     - "Response output content encoding format is identified with the
       Accept header in the request.  If is not specified, the request
       input encoding format is used." This deviates from the
       semantics of HTTP Accept header. RFC 7231: "A request without
       any Accept header field implies that the user agent will accept
       any media type in response."
**** Sec. 6.4
     - example-mod should have "prefix" statement 

*** Typos etc. 
    - sec. 2.5, last paragraph: s/For when/When/
    - sec. 4: The table is numbered (Table 1), other tables in the
      document aren't
    - the titles of sections 4.8.7-9 contain non-breaking hyphen
      (U+2011) which is not rendered in the table of contents

-- 
Ladislav Lhotka, CZ.NIC Labs
PGP Key ID: E74E8C0C