Subject: Re: [Netconf] LL review of restconf-09

From: Robert Wilton <[email-masked]>
Date: Wed, 17 Feb 2016 18:02:52 +0000

To add to Lada's comment below:
"

**** Sec. 3.5
      - first paragraph: leaf-list entries aren't data resources? And
        shouldn't it in fact be "Every instance of a container, ..."?

"
It was unclear to me in section 3.5.1 whether the data resource 
identifier list encoding applies only to YANG lists, or to leaf-lists as 
well.

In particular, it wasn't clear to me how the "point" query parameter is 
to be encoded for insert before/after in leaf-lists.

Thanks,
Rob

On 11/01/2016 10:35, Ladislav Lhotka wrote:
> 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
>

---

From: Andy Bierman <[email-masked]>
Date: Wed, 17 Feb 2016 10:11:49 -0800

Hi,

This will be clarified in draft-10. A leaf-list instance is a resource.
It is identified by its value.

   /restconf/data/leaf-list=test1

Andy

On Wed, Feb 17, 2016 at 10:02 AM, Robert Wilton <[email-masked]> wrote:

> It was unclear to me in section 3.5.1 whether the data resource identifier
> list encoding applies only to YANG lists, or to leaf-lists as well.
>
> In particular, it wasn't clear to me how the "point" query parameter is to
> be encoded for insert before/after in leaf-lists.
>
> Thanks,
> Rob
>
>
> _______________________________________________
> Netconf mailing list
> [email-masked]
> https://www.ietf.org/mailman/listinfo/netconf
>

---

From: Robert Wilton <[email-masked]>
Date: Thu, 18 Feb 2016 09:52:35 +0000

Hi Andy,

Thanks for the clarification.

I have one further question based on your answer:

Given that a leaf-list instance is a resource, am I correct in presuming 
that sections 3.4.1.1/3.4.1.2 (Timestamp/Entity tag) imply that each 
instance in a leaf-list "SHOULD" have its own timestamp and entity tag?

Thanks,
Rob

On 17/02/2016 18:11, Andy Bierman wrote:
> On Wed, Feb 17, 2016 at 10:02 AM, Robert Wilton <[email-masked] 
> <mailto:[email-masked]>> wrote:
>
>     identifier list encoding applies only to YANG lists, or to
>     leaf-lists as well.
>
>     In particular, it wasn't clear to me how the "point" query
>     parameter is to be encoded for insert before/after in leaf-lists.
>
>     Thanks,
>     Rob
>
>
>                   Host: example.com <http://example.com>
>                   If-Match: b8389233a4c
>               - Is this legal:
>         "fields=jukebox(library/artist;playlist)/name"?
>     [email-masked] <mailto:[email-masked]>

---

From: Andy Bierman <[email-masked]>
Date: Thu, 18 Feb 2016 09:11:20 -0800

> instance in a leaf-list "SHOULD" have its own timestamp and entity tag?
yes

Andy