Subject: [Netconf] Representing URLs

From: Wojciech Dec <[email-masked]>
Date: Fri, 29 Nov 2013 15:01:36 +0100

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

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?

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

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?

Thanks,
Wojciech.

---

From: Juergen Schoenwaelder <[email-masked]>
Date: Fri, 29 Nov 2013 16:02:57 +0100

> //some Xpath expression to a node

An instance-identifier is not a URI.
 
> paths, there appear to be a couple of problems in terms of  a Restful API:

A path is not a URI either. It seems you are talking about some form of
paths but not URIs.

That said, I may agree that having a hard-wired logic how URIs to
RESTful resources are constructed is somewhat unRESTful. It seems that
discovery of URIs for such resources is what people prefer. But of
course, the flexibility this allows comes at a price - you sometimes
neeed to do additional lookups. The good news is that HTTP is
providing decent caching support.

/js

> this would actually work in A or B above. Would it, or is there some other

/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: Andy Bierman <[email-masked]>
Date: Fri, 29 Nov 2013 07:59:41 -0800

On Fri, Nov 29, 2013 at 6:01 AM, Wojciech Dec <[email-masked]> wrote:

> Currently Yang allows two forms by which one could seek to have URI data
> be represented in a model:
>
> A.
> leaf someUri {
> 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

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?

>         "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.

> this would actually work in A or B above. Would it, or is there some other

The URI is not an XPath expression. There are no predicates allowed,
I don't think current() is allowed outside a predicate.

> Wojciech.
Andy

---

From: Wojciech Dec <[email-masked]>
Date: Fri, 29 Nov 2013 17:00:35 +0100

> An instance-identifier is not a URI.

Granted, but
http://tools.ietf.org/html/draft-bierman-netconf-restconf-02#page-57 speaks
about how it ends up being a URI, possibly a URL, in the context of
Now, what is missing, or  at least not clear to me, is how this data-type
ends up being transformed into something more usable in a Rest context (IMO
a canonical URL). And then the other bits and pieces 1-3 below.

> A path is not a URI either. It seems you are talking about some form of

With Restconf, the Yang data-nodes are effectively being mapped to Restful
resources, accessible via URLs.
Putting URLs direlcty into the data model does not look right, so I'm
looking at ways in which these URLs could be generated by Restconf.

Cheers,
Wojciech.

> generation

---

From: Andy Bierman <[email-masked]>
Date: Fri, 29 Nov 2013 08:24:19 -0800

On Fri, Nov 29, 2013 at 8:00 AM, Wojciech Dec <[email-masked]> wrote:

> http://tools.ietf.org/html/draft-bierman-netconf-restconf-02#page-57speaks about how it ends up being a URI, possibly a URL, in the context of

There is a canonical UR for a data resource returned in the Location header
when a resource is created.  The URI path is constructed.  First the client
needs to know the URL to the predicable datastore

   http://server.example.com/restconf/config

Datastore resources can only have data resources as child nodes.
The URI for the data node is concatenated to the URI for the datastore.

> looking at ways in which these URLs could be generated by Restconf.
The co-authors have discussed a retrieval mode to have the URL of the data
nodes returned.
The client can currently use the query parameter  "depth=2" to discover
just the child nodes
of the entry point, and walk the tree just as they would retrieving
meta-data instead.

The problem with always returning these URLs is that the size of the
replies goes up
by 8 or 10 fold.

Cheers,

Andy

---

From: Wojciech Dec <[email-masked]>
Date: Fri, 29 Nov 2013 18:33:00 +0100

On 29 November 2013 16:59, Andy Bierman <[email-masked]> wrote:
>> 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 {
>> 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:
>> {
> 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
> 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?
>
>

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.

>> 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.
>> Thus, is there a way to have Restconf return an RPC/services list for the data? Eg:
>>
>> {
>>     "songs":
>>     [

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"

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

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.

---

From: Andy Bierman <[email-masked]>
Date: Fri, 29 Nov 2013 10:07:21 -0800

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

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

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.

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

> "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.

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