Re: [Netconf] Representing URLs

[Martin Bjorklund <[e-mail]>]

Andy Bierman <[e-mail]> wrote:
> 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).


Good point!


/martin