Re: [Netconf] Representing URLs

[Andy Bierman <[e-mail]>]

On Wed, Dec 4, 2013 at 6:57 AM, Wojciech Dec <[e-mail]> wrote:

> On 4 December 2013 13:33, Ladislav Lhotka <[e-mail]> wrote:
> >
> > On 04 Dec 2013, at 11:10, Wojciech Dec <[e-mail]> wrote:
> >
> >> On 3 December 2013 20:40, Ladislav Lhotka <[e-mail]> wrote:
> >>>
> >>> On 03 Dec 2013, at 18:47, Wojciech Dec <[e-mail]> wrote:
> >>>
> >>>> On 3 December 2013 16:58, Ladislav Lhotka <[e-mail]> wrote:
> >>>>>
> >>>>> On 03 Dec 2013, at 16:39, Wojciech Dec <[e-mail]> wrote:
> >>>>>
> >>>>>> Following up some of my earlier questions... Inline...
> >>>>>>
> >>>>>> On 29 November 2013 16:59, Andy Bierman <[e-mail]> wrote:
> >>>>>>>
> >>>>>>>
> >>>>>>>
> >>>>>>> On Fri, Nov 29, 2013 at 6:01 AM, Wojciech Dec <[e-mail]>
> wrote:
> >>>>>>>>
> >>>>>>>> Hello Restconf authors,
> >>>>>>>>
> >>>>>>>> I would like to ask a few questions and seek your thoughts on the
> topic of
> >>>>>>>> URL representation in the API
> >>>>>>>> Currently Yang allows two forms by which one could seek to have
> URI data
> >>>>>>>> be represented in a model:
> >>>>>>>>
> >>>>>>>> A.
> >>>>>>>> leaf someUri {
> >>>>>>>>  type instance-identifier;
> >>>>>>>> //some Xpath expression to a node
> >>>>>>>> }
> >>>>>>>>
> >>>>>>>> B.
> >>>>>>>> leaf anotherUri {
> >>>>>>>>  type yang:uri;
> >>>>>>>>  default "/my_uri/is/here"
> >>>>>>>> }
> >>>>>>>>
> >>>>>>>> Now, while the above is perhaps sufficient for some well known
> absolute
> >>>>>>>> paths, there appear to be a couple of problems in terms of  a
> Restful API:
> >>>>>>>>
> >>>>>>>> 1. Based on the current Restconf spec, both A and B above when
> faced with
> >>>>>>>> a GET would appear to expose a URI, which the client would have
> to do some
> >>>>>>>> manipulation magic on it before use. What a Restful API would be
> more likely
> >>>>>>>> to expose instead is a URL, eg in JSON:
> >>>>>>>> {
> >>>>>>>>  "url" : "http://example.com/files/v1/documents/abc123"
> >>>>>>>> }
> >>>>>>>
> >>>>>>>
> >>>>>>>
> >>>>>>> I do not understand the concern.
> >>>>>>> One leaf is //restconf/config/someUri and the other is
> >>>>>>> /restconf/config/anotherUri.
> >>>>>>> What is the manipulation magic?  Constructing /path/to/data/node
> based on
> >>>>>>> YANG?
> >>>>>>> That is the point of RESTCONF.  There are already plenty of
> solutions for
> >>>>>>> using
> >>>>>>> REST APIs for ad-hoc data.  I do not see any reason to develop
> RESTCONF for
> >>>>>>> clients that want to ignore YANG.  There are already have plenty
> of choices
> >>>>>>> for that.
> >>>>>>>
> >>>>>>>
> >>>>>>>>
> >>>>>>>>
> >>>>>>>> It would appear to be sensible to add to the Restconf spec a URL
> >>>>>>>> generation capability. I.e. have Restconf transform URIs into
> canonical
> >>>>>>>> URLs. Thoughts?
> >>>>>>>
> >>>>>>>
> >>>>>>> Can you describe the solution you have in mind?
> >>>>>>>
> >>>>>>>>
> >>>>>>>>
> >>>>>>>> 2. A URL to a data-model specific method
> >>>>>>>> Suppose that the model was also defining an RPC, along the lines
> of the
> >>>>>>>> "play" RPC in the Jukebox example. Now, as part of the song
> resource access
> >>>>>>>> API, it would be natural to have such a method returned in a URL.
> That would
> >>>>>>>> also be much more Resful than the currently implicit
> "/operations" resource
> >>>>>>>> listing.
> >>>>>>>> While it may be possible to use B. above to some degree, that is
> still
> >>>>>>>> below par as it is not validated in the model.
> >>>>>>>> Use of A. appears, to me at least, not possible since the RPC is
> not a
> >>>>>>>> node.
> >>>>>>>> Thus, is there a way to have Restconf return an RPC/services list
> for the
> >>>>>>>> data? Eg:
> >>>>>>>>
> >>>>>>>> {
> >>>>>>>>  "songs":
> >>>>>>>>  [
> >>>>>>>>      a list of songs, 1, 2, etc
> >>>>>>>>  ],
> >>>>>>>>  "rpc":
> >>>>>>>>  {
> >>>>>>>>      "play": [ "
> http://example.com/operations/example-jukebox:play"]
> >>>>>>>>  }
> >>>>>>>> }
> >>>>>>>>
> >>>>>>>
> >>>>>>> The API already has /restconf/operations/<YANG-rpc-name>.
> >>>>>>>
> >>>>>>> YANG is not object-oriented, so /restconf/config/routing/<RPC-name>
> >>>>>>> is not how the RPC is defined.  You are describing a proprietary
> >>>>>>> extension.
> >>>>>>>
> >>>>>>>> 3. Use of current() function as predicate in URIs/URLs
> >>>>>>>>
> >>>>>>>> It would be useful to be able to use the "current()" function to
> construct
> >>>>>>>> URIs/URLs returned in Restconf. The spec does not make it clear
> on whether
> >>>>>>>> this would actually work in A or B above. Would it, or is there
> some other
> >>>>>>>> way?
> >>>>>>>>
> >>>>>>>
> >>>>>>>
> >>>>>>> The URI is not an XPath expression. There are no predicates
> allowed,
> >>>>>>> I don't think current() is allowed outside a predicate.
> >>>>>>
> >>>>>> Ok, so what is the way in Yang to have a predicate (e.g. current())
> >>>>>> based expression that ends up being represented as a URI in
> Restconf?
> >>>>>> Use of the current() predicate in the instance-identifier appears
> not
> >>>>>> to be supported (at least by pyang).
> >>>>>
> >>>>> Predicates in instance-identifiers can be used only for matching
> list keys against constant strings, see sec. 9.13 in RFC 6020.
> >>>>>
> >>>>> Can you give an example of an effect you would like to achieve?
> >>>>
> >>>> Starting with a basic example: In a data-model for interfaces/x/y, I
> >>>> would like the ability to actually have a reference to another node in
> >>>> the model, that in Restconf ends up shwoing up as a URI. Eg. getting
> >>>> at the URI /interfaces/x/y, would return data which would also give me
> >>>> a URI for "/line-cards/foo/serial-number".
> >>>>
> >>>> A hypothetical Yang data-model for this could be:
> >>>> list interfaces {
> >>>>   key some;
> >>>>   leaf some {
> >>>>      type string;
> >>>>   }
> >>>>   list details;
> >>>>     key id;
> >>>>     leaf id {
> >>>>       type string;
> >>>>     }
> >>>>    Other stuff
> >>>>    leaf someUri {
> >>>>        type instance-identifier;
> >>>>    // Xpath expression to the line-cards/foo
> >>>>    }
> >>>>  }
> >>>> }
> >>>
> >>> Assuming that line-cards also appear somewhere in the data tree, a
> leafref would be a more natural way of representing the reference - and
> then you can use current(), too.
> >>>
> >>> I have myself never used an instance-identifier in any data model yet,
> presumably they are mainly useful in notifications.
> >>
> >> So leafrefs are great, but if I interpret them correctly in rfc6020
> >> (http://tools.ietf.org/html/rfc6020#page-124), their usage in the
> >> context of Restconf would result not in a URI for the leaf being
> >> passed to a client (say after a GET), but rather the value of that
> >> leaf. It also does not appear to be suited to referencing a data node
> >> (eg container).
> >
> > In my view, the leafref value (such as a list key) can be passed in in a
> GET response and then it should be easy for the client-side application to
> construct the corresponding URI, XPath or whatever, because it has access
> to the data model. I know this goes against REST catechism but I am
> inclined to consider it a feature, not a bug.
>
> It would be better to call it a missing feature.
> Leafref is fine as is, and does pass the value. The recipient though
> has no idea how to access the resource of that value unless the whole
> (sub) tree is conveyed.
> Using the example from 6020:
>
>   leaf mgmt-interface {
>          type leafref {
>              path "../interface/name";
>          }
>      }
>
>    An example of a corresponding XML snippet:
>
>      <interface>
>        <name>eth0</name>
>      </interface>
>      <interface>
>        <name>lo</name>
>      </interface>
>
>      <mgmt-interface>eth0</mgmt-interface>
>
> A client receiving eth0, has no idea about the URI of that resource.
> Assuming that the client is coded to the data model, or is fully Yang
> aware, and able to combine the "path ../interface/name" to make sense
> of it all, is not just going against REST principles; it forces a
> tight client-server coupling, even when one would not be required. I
> expect a good number of client applications wishing to access he data
> via Restconf, without necessarily having interest in the full
> data-models, or even in altering configurations (eg reading a
> topology).
> As I wrote previously, having the option of Yang aware clients vs pure
> REST would be a much stronger proposition.
> What can we do to get the missing feature?
>
> I would still see the "instance-identifier" either molded into a URI,
> or a new "instance-identifier" like data-type that allow that.
>
> Thoughts?
>
>


The client has the YANG model, otherwise it would not be
doing anything but attempt to render this leaf, since it doesn't
know the semantics or even the derived type (i-i or leafref).

If the client knows the YANG, then it knows the general
path expression to the referenced leaf.  These leafs are not
required to be unique (e.g., point at if-type leaf).  The leafref
object must be set to 1 of the values that exist on the device.
Your example points at a key leaf, but a keyref is just 1 form
of a leafref.

You seem to be assuming that the path-stmt nodeset must evaluate
to a single instance, and the client must be able to retrieve this instance.
However YANG leafref is not defined that way.  The value is not tied
to a specific referenced leaf instance, so the client cannot retrieve the
instance-identifier of that leaf (or all matching leafs).





> -Wojciech.
>
> >
> > Lada
>

Andy