Subject: [Netconf] draft-ietf-netconf-restconf-09 review comments

From: "Uveges, Balint (Nokia - HU/Budapest)" <[email-masked]>
Date: Fri, 22 Jan 2016 15:47:01 +0000

Hi all,

I've reviewed the latest restconf draft and I would like to share my thoughts and comments. Otherwise I think the document is in fairly good shape.

1. XML Examples
Through the document I couldn't find that many XML payload examples. Especially the POST (Create Resource Mode) and PUT method lacks of that. I understand that from JSON point of view every HTTP method is covered, but it would greatly enhance the document, if that would be also true for XML.

2. POST (Create Resource Mode) vs. XML
Chapter 4.4.1 says:
   If the target resource type is a datastore or data resource, then the
   POST is treated as a request to create a top-level resource or child
   resource, respectively.  The message-body is expected to contain the
   content of a child resource to create within the parent (target
   resource).

If my understanding is correct, that means (taking the example-jukebox module as an example), if I apply a POST on the artist resource to create two new albums, I would have something like this in case of XML encoding, because it only contains the content of the child resources:
      POST /restconf/data/example-jukebox:jukebox/
          library/artist=Foo%20Fighters  HTTP/1.1
      Host: example.com
      Content-Type: application/yang.data+xml

     <album xmlns="http://example.com/ns/example-jukebox">
      <name>Wasting Light</name>
      <genre xmlns:g="http://example.com/ns/example-jukebox">
        g:alternative
      </genre>
      <year>2011</2011>
     </album>
     <album xmlns="http://example.com/ns/example-jukebox">
      <name>Sonic Highways</name>
      <genre xmlns:g="http://example.com/ns/example-jukebox">
        g:alternative
      </genre>
      <year>2014</2011>
    </album>

But that would result in an XML that is not well formed, since it does not have one root parameter. My assumption is, that if I create a new resource, I should also include the parent resource's, like:
    <artist>
      <album xmlns="http://example.com/ns/example-jukebox">
        <name>Wasting Light</name>
    ...etc, etc...
    </artist>

Could you verify which approach is correct? Would it make sense to reflect that in the document?

3. Status code
I have somewhat the feeling, that the Status Code table is not in the right place in the 7th chapter. The table also contains 1xx and 2xx codes, that are not about error reporting. Wouldn't it make sense, to move the table to a separate chapter? Also, the status code 202 Accepted is only mentioned here in the whole document. Shouldn't it receive some extra care? I mean to describe the semantics behind 202?

Thank you,
Best regards:
-Balint

---

From: Andy Bierman <[email-masked]>
Date: Fri, 22 Jan 2016 09:43:05 -0800

On Fri, Jan 22, 2016 at 7:47 AM, Uveges, Balint (Nokia - HU/Budapest) <
[email-masked]> wrote:

> Hi all,
>
> I've reviewed the latest restconf draft and I would like to share my
> thoughts and comments. Otherwise I think the document is in fairly good
> shape.
>
> 1. XML Examples
> Through the document I couldn't find that many XML payload examples.
> Especially the POST (Create Resource Mode) and PUT method lacks of that. I
> understand that from JSON point of view every HTTP method is covered, but
> it would greatly enhance the document, if that would be also true for XML.
>
>
We can add more examples I guess.
Understanding XML or JSON is not really the scope of this document.

> If my understanding is correct, that means (taking the example-jukebox
> module as an example), if I apply a POST on the artist resource to create
> two new albums, I would have something like this in case of XML encoding,
> because it only contains the content of the child resources:
> But that would result in an XML that is not well formed, since it does not
> have one root parameter. My assumption is, that if I create a new resource,
> I should also include the parent resource's, like:
>     <artist>
You have to use YANG Patch to modify multiple subtrees at once.
HTTP/REST allows 1 resource to be altered or retrieved at a time.

> 3. Status code
> I have somewhat the feeling, that the Status Code table is not in the
> right place in the 7th chapter. The table also contains 1xx and 2xx codes,
> that are not about error reporting. Wouldn't it make sense, to move the
> table to a separate chapter? Also, the status code 202 Accepted is only
> mentioned here in the whole document. Shouldn't it receive some extra care?
> I mean to describe the semantics behind 202?
>
>
I guess we can change the section name and add more text about 202 Accepted.

> -Balint

Andy

> _______________________________________________
> Netconf mailing list
> [email-masked]
> https://www.ietf.org/mailman/listinfo/netconf
>

---

From: Juergen Schoenwaelder <[email-masked]>
Date: Sun, 24 Jan 2016 11:43:44 +0100

> HTTP/REST allows 1 resource to be altered or retrieved at a time.

Is the resource not /restconf/data/example-jukebox:jukebox/ in this
case?

/js

-- 
Juergen Schoenwaelder           Jacobs University Bremen gGmbH
Phone: +49 421 200 3587         Campus Ring 1 | 28759 Bremen | Germany
Fax:   +49 421 200 3103         <http://www.jacobs-university.de/>

---

From: Andy Bierman <[email-masked]>
Date: Sun, 24 Jan 2016 06:55:00 -0800

On Sun, Jan 24, 2016 at 2:43 AM, Juergen Schoenwaelder <
[email-masked]> wrote:

> > > Could you verify which approach is correct? Would it make sense to
> reflect
> > > that in the document?
> > >
> > >
You can patch the jukebox with multiple 'create' edits.
What is your concern?

Andy

---

From: Juergen Schoenwaelder <[email-masked]>
Date: Mon, 25 Jan 2016 10:17:24 +0100

> You can patch the jukebox with multiple 'create' edits.

My main concern is fair answers to reasonable questions that people
ask. If the restriction here is an XML one, then this may need to be
spelled out (plus any guidelines how to deal with this) so that people
do not have to ask this question.

/js