Re: [Netconf] Representing URLs

[Andy Bierman <[e-mail]>]

On Fri, Nov 29, 2013 at 9:33 AM, Wojciech Dec <[e-mail]> wrote:

> 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?
>
>
> Well, so two "magical manipulation" pieces appear to be:
> i) The adding of the "/restconf/config/" path part.
> ii) Actually making a URL out of this.
>
> Neither of these appears to have to do with Yang as such.
>
> >
> > 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.
>
>
> Uhm, does RESTCONF requires a special client to be used? I.e. one
> having special behaviour/capabilities defined in the restconf spec.
> Personally, i see the construction of the REST APIs by the server,
> based on the Yang model as the major point of Restconf, irrespective
> of what the client side has. That in itself is a big plus.
> Naturally a client is free to "share" a model with the server, should
> one choose that approach - but it's not a must as the server's Resful
> API provides a contract, in this case data model driven.
>
>

It does not need a special client, but clients that know nothing about the
data
they are using can do little more than render it as valid XML or JSON.  A
client could
be hard-wired based on media type, and not use YANG.

I am not against a retrieval mode where the client retrieves the full
Location
header line for the target resource. The server could return the Location
header for the target resource every GET (and make every reply that much
bigger).
These are the sorts of engineering trade-offs the WG decides by consensus.



> >
> >
> >
> >>
> >>
> >> 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?
>
>
> Let's use an ad-hoc modified jukebox as an example:
>
> container jukebox {
>         container library {
>           list artist {
>             key name;
>             leaf name {
>               type string;
>             }
>
>             list album {
>               key name;
>
>               leaf-list influences {
>
>                 type instance-identifier; //For lack of a better choice
>               }
>             }
>           }
>        }
> }
>
> Now, suppose foobar_artist1, 2 and 3 are there, with 2 and 3 being put
> in as influnces for 1. when doing a GET to
>
> http://example.com/restconf/config/example:jukebox/library/artist/foobar_artist1
>
> The entries on the influences list would end up being shown via
> Restconf in JSON as URLs, ie:
>
>
> { ...some album...
> "influences" : [
>      "url" : "
> http://example.com/restconf/config/example:jukebox/library/foobar_artist2
> ",
>      "url" : "
> http://example.com/restconf/config/example:jukebox/library/foobar_artist3"
>       ]
> }
>
>

You wouldn't use YANG instance-identifier if you wanted this format.
Use the data-resource-identifier typedef instead.

But I see your point.  The description-stmt says start with the doc-root,
not a full URI.
I agree the server needs to accept a full URI or a path string, and always
return
the full URI as the canonical format.

Also, this is not the correct encoding:
A leaf-list maps to a a JSON array of the leaf-list type.

leaf-list influences {
   type data-resource-identifier;
}

{
  "influences" : [
    "
http://example.com/restconf/config/example:jukebox/library/foobar_artist2",
    "
http://example.com/restconf/config/example:jukebox/library/foobar_artist3"
  ]
}


Other variations can also be made, including the of having Restconf
> making all 2nd level elements be served up as URLs instead of detail,
> which would be a good idea overall, but one would still like the
> ability to just have a URL reference when needed.
>
> >
> >
> >>
> >>
> >> 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.
>
>
> Well, typo aside*, as I said above the point is to have the API return
> a link to the rpc operations applicable to the data. In other words,
> either in the data model or in the API spec it should be possible to
> convey to the client the RPCs that are there. The fact that it is
> there under /restconf/operations/<name> is cool, but it's not
> sufficent to a restful client. Granted, one could make these some part
> of a own Restconf implementation, but this is actually something that
> would appear to be worthy of the spec.
>
> * Corrected
> "play": "http://example.com/restconf/operations/example-jukebox:play"
>
>
This seems to be outside the scope of plain REST.
There is no point in POSTing data with no idea
what input parameters are required.  Retrieving and
editing resources with CRUD operations is fine,
but the client needs to know the YANG rpc definitions
in order to use custom operation resources.  They are optional
for the server to support.


>
> >> 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.
>
>
> Yes, but the current instance-identifier is an XPath expression.
> However, I have not found any examples of current() being used in
> there though (and few examples of any use with an xpath expression at
> all). Would assuming that the instance-identifier gets munged to/from
> a URI by Restconf, be then sufficient?
>
>
The current() function is not even allowed in an instance-identifier.
It is very restricted subset of an XPath  absolute-path-expr.
A data-resource-identifier is a URL-encoded path string with the list keys
inserted as path components.


Wojciech.
>

Andy