Re: [Netconf] Representing URLs

[Wojciech Dec <[e-mail]>]

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 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"
      ]
}

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"

>
>> 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?

Wojciech.
>
>
>>
>> Thanks,
>> Wojciech.
>>
>
> Andy
>