Subject: [Netconf] restconf confusing text

From: Martin Bjorklund <[email-masked]>
Date: Fri, 26 Aug 2016 09:55:28 +0200 (CEST)

Hi,

I got a comment from a guy implementing RESTCONF regarding this text
in section 4.3 GET:

   If a retrieval request for a data resource representing a YANG leaf-
   list or list object identifies more than one instance, and XML
   encoding is used in the response, then an error response containing a
   "400 Bad Request" status-line MUST be returned by the server.

First of all, what exactly is such a retrieval request?

Second, it seems to say that we can never add something like
collections, since this spec require us to return a 400 in this case.

I suggest that this paragraph is removed.

/martin

---

From: [email-masked] (Dale R. Worley)
Date: Fri, 26 Aug 2016 17:03:20 -0400

> First of all, what exactly is such a retrieval request?

That can happen because the path of the request need not identify a
unique leaf.  Consider a modification of example-jukebox from section C.1 of
draft-ietf-netconf-restconf-15:

      container jukebox {
        presence
          "An empty container indicates that the jukebox
           service is available";

        description
          "Represents a jukebox resource, with a library, playlists,
           and a play operation.";

	// state data
        config false;

        container library {

          description "Represents the jukebox library resource.";

          list artist {
	    // no key

            leaf name {
              type string {
                length "1 .. max";
              }
              description "The name of the artist.";
            }

            ...

You can request

   GET /restconf/data/example-jukebox:jukebox/library/artist/name HTTP/1.1
   Host: example.com
   Accept: application/yang-data

But since jukebox is not state data (i.e., is read-only), then there is
no key for the list "artist", and the URL collectively identifies all
name children of all elements of the list "artist".

If the returned data is to be application/yang-data+json, JSON can
return multiple values.  But if the returned datais to be
application/yang-data, XML cannot return return multiple values.

Dale

---

From: Martin Bjorklund <[email-masked]>
Date: Mon, 29 Aug 2016 11:18:27 +0200 (CEST)

> name children of all elements of the list "artist".

Note that the original text talks about a request for a "data
resource" representing more than one instance.  But "data resource" is
a well-defined term that refers to a node in the data tree.  data
resource maps one-to-one to data node, so it is not possible for a
data resource to "identify mote than one instance".

> application/yang-data, XML cannot return return multiple values.

Sure it can, but it needs to be wrapped in something like a
<collection> element (as was the original idea behinf collections).

And just b/c JSAON can return multiple values, it doesn't mean that
the RESTCONF spec has defined support for such collections for JSON.

/martin

---

From: Kent Watsen <[email-masked]>
Date: Mon, 29 Aug 2016 13:09:49 +0000

I assume that “retrieval request” should be “GET request”.   

I’m not sure if it’s okay to just delete the paragraph.  It seems that there needs to be some guidance to handle this case, as otherwise implementations will vary.     

Assuming the collections draft would ‘update’ this draft, could it not provide an alternate solution for when a collections-specific query parameter is used - effectively overriding this paragraph.  Unfortunately, this would lead to a requirement that a collections-specific query parameter always needs to be passed, even for the trivial case when none would have to be passed otherwise (i.e., give me everything with no sorting or paging).

PS: to bad the collections support isn’t in this draft  ;)

Kent

On 8/26/16, 3:55 AM, "Netconf on behalf of Martin Bjorklund" <[email-masked] on behalf of [email-masked]> wrote:

    Hi,

    

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

---

From: Martin Bjorklund <[email-masked]>
Date: Mon, 29 Aug 2016 15:18:43 +0200 (CEST)

Kent Watsen <[email-masked]> wrote:
> I’m not sure if it’s okay to just delete the paragraph.  It seems that
> there needs to be some guidance to handle this case, as otherwise
> implementations will vary.

Can you show me an example of "this case"?  See also my reply to Dale
W. today.

/martin

> 
> Assuming the collections draft would ‘update’ this draft, could it not
> provide an alternate solution for when a collections-specific query
> parameter is used - effectively overriding this paragraph.
> Unfortunately, this would lead to a requirement that a
> collections-specific query parameter always needs to be passed, even
> for the trivial case when none would have to be passed otherwise
> (i.e., give me everything with no sorting or paging).
> 
> On 8/26/16, 3:55 AM, "Netconf on behalf of Martin Bjorklund"
> <[email-masked] on behalf of [email-masked]> wrote:
> 
>     Hi,
>

---

From: [email-masked] (Dale R. Worley)
Date: Mon, 29 Aug 2016 10:09:16 -0400

> data resource to "identify mote than one instance".

Well, I take "resource" to be "the thing identified by a URL", and so
"resource" maps one-to-one to URL, and some URLs identify multiple data
nodes.  I mean, the "R" in "URL" stands for "resource".  I'm not privy
to the full history behind this document, but the text of the document
seems to be consistent with my interpretation, along with all of the
HTTP documentation.

> <collection> element (as was the original idea behinf collections).

Yeah, but this document didn't define that.  I can see some advantage if
it had.  But it seems that the authors decided not to do that, which
leads to the oddly asymmetric restriction that you can do a GET of a
multiple-instance URL if the response is allowed to be in JSON but not
if the response is in XML.

Since multiple-resource URLs can only identify state data, which is
read-only, trying to do a POST, DELETE, or PATCH against one fails for
that reason, which is why only GET needs this special consideration.

> the RESTCONF spec has defined support for such collections for JSON.

I've been assuming that that support is implicit in JSON, and I know
little about JSON.  But if it's *not* a conventional part of JSON, that
needs to be spelled out in the document.

Dale

---

From: Kent Watsen <[email-masked]>
Date: Mon, 29 Aug 2016 14:13:23 +0000

On 8/29/16, 9:18 AM, "Martin Bjorklund" <[email-masked]> wrote:

Same as Dale’s example.   Are you trying to make the point that it is not technically a “resource” and therefore not a proper GET target, and thus the document doesn’t need to say anything about it?

K.

---

From: Martin Bjorklund <[email-masked]>
Date: Mon, 29 Aug 2016 16:38:01 +0200 (CEST)

> if the response is in XML.

I don't think that this document specifies how the reply to a
"multi-instance URL" would work for JSON.  For example, what would the
reply be for /interfaces-state/interface/ipv4/address, assuming there are
multiple addresses defined on multiple interfaces?

> Since multiple-resource URLs can only identify state data

What text in the document says this?

/martin

> , which is

---

From: Martin Bjorklund <[email-masked]>
Date: Mon, 29 Aug 2016 16:39:02 +0200 (CEST)

Kent Watsen <[email-masked]> wrote:
> Same as Dale’s example.  Are you trying to make the point that it is
> not technically a “resource” and therefore not a proper GET target,
> and thus the document doesn’t need to say anything about it?

It's not technically a "data resource", and thus this document doesn't
have to say anything about it.

/martin

---

From: Kent Watsen <[email-masked]>
Date: Mon, 29 Aug 2016 15:10:05 +0000

On 8/29/16, 10:39 AM, "Martin Bjorklund" <[email-masked]> wrote:

    /martin

In that case, I agree with your assessment, but feel that this document should still say something about.  Specifically, I think it should say something along the lines of what you just wrote above.

Kent

---

From: Juergen Schoenwaelder <[email-masked]>
Date: Mon, 29 Aug 2016 18:36:42 +0200

> In that case, I agree with your assessment, but feel that this document should still say something about.  Specifically, I think it should say something along the lines of what you just wrote above.

Stupid question: Is there an HTTP status code that can be returned in
these cases (e.g., 406 Not Acceptable)? A future specification can
then define how to handle these requests.

/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: Nick Weeds <[email-masked]>
Date: Tue, 30 Aug 2016 10:17:04 +0000

In case it helps other readers: I believe it is possible to perform the get the artist name information in Dale's example using:

   GET /restconf/data/example-jukebox:jukebox/library;fields=artist/name HTTP/1.1

instead of

The former satisfies the requirement that the target (/restconf/data/example-jukebox:jukebox/library) is a "data resource".
The response would be a single "library" object containing multiple artist list entries, and would be valid in both XML and JSON encodings.

	Nick.

-----Original Message-----
From: Netconf [mailto:[email-masked]] On Behalf Of Kent Watsen
Sent: 29 August 2016 16:10
To: Martin Bjorklund
Cc: [email-masked]
Subject: Re: [Netconf] restconf confusing text

        
    /martin

Kent

---

From: Kent Watsen <[email-masked]>
Date: Tue, 30 Aug 2016 12:45:20 +0000

True, the “library” node is a data resource, with or without the query parameters.  Note that it is a ‘container’ node (not a list or leaf-list), which is why it works.  BTW, query parameters are separated by a ‘?’ (not ‘;’) character. So the request should’ve been:

	       GET /restconf/data/example-jukebox:jukebox/library?fields=artist/name HTTP/1.1

BTW, I’m not sure if the example in D.3.3 is correct.  It seems that it should return a “data” object (not a “modules-state” object).

Cheers,
Kent

On 8/30/16, 6:17 AM, "Netconf on behalf of Nick Weeds" <[email-masked] on behalf of [email-masked]> wrote:

    
    instead of

    
    	Nick.

    -----Original Message-----
    From: Netconf [mailto:[email-masked]] On Behalf Of Kent Watsen
    Sent: 29 August 2016 16:10
    To: Martin Bjorklund
    Cc: [email-masked]
    Subject: Re: [Netconf] restconf confusing text

    

        /martin

    Kent

---

From: [email-masked] (Dale R. Worley)
Date: Tue, 30 Aug 2016 10:23:10 -0400

Martin Bjorklund <[email-masked]> writes:
> "multi-instance URL" would work for JSON.

Indeed, it doesn't (as far as I remember).  As I said,

> What text in the document says this?

The only way you can create a multi-node URL is to explot the fact that
some lists do not have unique keys, allowing you to write the list node
name as a path segment in the URL without providing a key value.  (In
Yang, the list statement doesn't have a key substatement.)  But only
non-configuration lists can have no key.  See
draft-ietf-netmod-rfc6020bis-14 section 7.8.2, or parallel statements in
RFC 6020 or later versions of the draft.

> have to say anything about it.

True, it doesn't fit within the definition of the term in the
terminology section.  But it's clear from the meanings of the text that
the writers *intended* for this sort of multi-node URL to be
implemented, and to mean what I've described.  So they need to fix the
language to match their intentions.

Or decide they're going to change the semantics of Restconf.

> then define how to handle these requests.

Yeah, in draft-ietf-netconf-restconf-15 section 4.3, it specifies 404 as
the response code:

Somewhat oddly, if the client gives the server the option of using
either XML or JSON in this situation, the server can either choose XML
and return 404 or choose JSON and return the requested data.  To ensure
that it will get the data, the client must allow JSON responses only.
But that is consistent.

Dale