Re: [Netconf] Fwd: I-D Action: draft-bierman-netconf-restconf-03.txt

[Wojciech Dec <[e-mail]>]

On 10 January 2014 11:37, Andy Bierman <[e-mail]> wrote:
>
>
>
> On Fri, Jan 10, 2014 at 1:37 AM, Wojciech Dec <[e-mail]> wrote:
>>
>> Hi Martin,
>>
>> On 8 January 2014 12:29, Martin Bjorklund <[e-mail]> wrote:
>> > Wojciech Dec <[e-mail]> wrote:
>> >> On 6 January 2014 12:49, Andy Bierman <[e-mail]> wrote:
>> >> >
>> >> >
>> >> >
>> >> > On Mon, Jan 6, 2014 at 3:33 AM, Wojciech Dec <[e-mail]>
>> >> > wrote:
>> >> >>
>> >> >> Hi Andy, all,
>> >> >>
>> >> >> are the issues leading to this draft  documented somewhere? The IETF
>> >> >> 88 minutes only talk about the yang patch aspect.
>> >> >>
>> >> >> Anyway, I took a read through the latest document and the change to
>> >> >> have all Yang data-nodes be resources. Am I correct in interpreting
>> >> >> it
>> >> >> that now  every leaf node  effectively becomes a resource with a
>> >> >> separate URI? Could the authors provide some more insight regarding
>> >> >> this change?
>> >> >>
>> >> >
>> >> >
>> >> >
>> >> > Since YANG Patch is now optional, there is no way to delete an
>> >> > optional leaf
>> >> > or leaf-list otherwise, except to copy the entire resource, and then
>> >> > replace
>> >> > the entire resource (minus the optional leaf).
>> >>
>> >>
>> >> I am still not able to get the full rationale for the change.  Can the
>> >> authors or chairs provide that?
>> >>
>> >> Anyway, it now appears that every single data leaf is a resource,
>> >> instead of an attribute
>> >
>> > Yes, every leaf is a subresource to its parent list or container.
>> > This just means that you can GET/POST/DELETE the leaf directly, w/o
>> > having to PATCH the parent.
>> >
>> >> and the spec doesn't specify a distinction
>> >> between handling parent resources and its sub-resources, e.g. At the
>> >> very least POST/PUT operations to sub resources need to be constrained
>> >> by their parent resource, and leaving that up to the implementation is
>> >> kind of a step backwards for the spec as a whole besides being IMO a
>> >> major complication for client or server, and likely both e.g how
>> >> should a change to a sub-resource that doesn't meet some condition of
>> >> the parent be handled? For a single parent resource, how should
>> >> multiple sub-resource changes be coordinated (the parent resource
>> >> needs to be consistent)? Etc.
>> >
>> > I am afraid I do not understand your concern.  Could you provide an
>> > example (data model and requests) that you feel is problematic or
>> > unclear?
>>
>>
>> A simple example:
>>
>>     container book {
>>
>>                 leaf price {
>>                      type string;
>>                  }
>>                 leaf tax-amount {
>>                      type string;
>>                  }
>>
>>      }
>>
>> Price and taxt are typically related.
>> A (better) REST API design would seek to minimize transactional
>> effects to the client while protecting the consistency/sanity of the
>> data: To update the resource, a POST operation to foo/book would carry
>> in the envelope both a new price and the tax amount. A (worse) REST
>> API design would expose both price and tax-amount as separate
>> resources, accept POST to both foo/book/price and foo/book/tax-amount
>> and hope-for-the-best that the client succeeds and all. Several non
>> trivial failuire scenarios come up here too.
>>
>> The key is that REST API design is very much about determining what is
>> a resource,  its representation by a URI, and what are the attributes
>> of a resource. In draft -03, everything is now a resource, and
>> everything is also attribute. This IMO ultimately complicates and
>> bloats code (on client, server, and likely both), and will lead to
>> brittle API and poor user experience.
>>
>> Another quick example:
>>
>>
>>     container book {
>>
>>                 list page {
>>                     key page-nr;
>>                     leaf page-nr {type string;}
>>                     leaf text {type string;}
>>                  }
>>      }
>>
>> The RESTConf URI for the above would <root stuff
>> here>/book/page/{page-nr}/text
>>
>> In general with REST APIs it is important that we do NOT expose the
>> dependent sub-resources directly thus allowing someone to create (POST
>> or PUT) to <root stuff here>/book/page/{page-nr}  without a book, or
>> text without a page, or other cases that do not make sense, and in
>> general requiring a feast of error cases.
>> Requiring the text POST/PUT  handler to also do book creation,
>> validation, etc, is not a great design. It complicates code and
>> creates ugly code dependencies, should the model change, etc.
>>
>>
>> >
>> >> If this current development was driven by questions/problems in the
>> >> support of HTTP Patch operation (incl. JSON patch), the solution
>> >> appears to be possibly worse than the supposed problem. That's why it
>> >> would be good to understand the rationale some more.
>> >
>> > If the "yang patch" media type is opitonal, there is no other way to
>> > delete optional leafs.  If the optional leaf is a resource it can be
>> > removed with DELETE.
>>
>> Yes, but the current "solution" is IMO a lot worse than a) mandating
>> PATCH, and I mean plain JSON/XML PATCH  or b) handling (specifying in
>> the draft how-to do) updates via POST. Thus bringing in back the
>> simple patch would be a good move. And the Yang patch is something
>> that can go into another spec, I agree.
>>
>
>
> Plain PATCH does not allow an optional leaf to be deleted.
> JSON patch does not work well with named data like YANG.
> Ignoring YANG naming and using integer indices that renumber
> every time a list is changed is a non-starter.  The only way to
> delete an optional leaf is to GET the entire parent resource,
> edit it offline (remove the leaf) and PUT the parent resource.
> This is operationally disruptive and expensive to implement
> in the server.  Optional leafs make up most configuration data,
> so a CM solution that doesn't work well for optional leafs is a bad idea.

I should have been clearer: Media Type discussion aside, I meant JSON
patch as in "json patch for json reresented yang data", ie likely a
subset of pure 'application/json-patch+json', with yang-patch being in
some other doc. . The fact that JSON patch does not work for xml is,
for me at least, not an issue. A simple answer can thus be that the
patch is for json only.
In general, I don't quite follow why you say that json patch doesn't
allow for leaf deletion; the "remove" op seems to be pretty much
intended for that. Gee, the json (yang) patch could even be just
limited to just this task.

That said, a solution to the " how to delete an optional leaf" problem
that ends up treating every data item in the system to a resource,
with no way for the designer to override, appears also as a bad idea.
Given that we have a full API spec here, even adding a custom
parameterized operation to the URI may be a better solution. Also,
evidence from the REST API world out there also indicates that for
better or worse, GET and PUT do actually work at scale. I would still
see this still as easier to deal with and implement than having every
single (sub-resource) data item as a resource....

So, in summary, "conservative" options, all leading to getting the
spec back from resource extremes as I see can be:
1. Stay with GET and PUT (I suspect that this is what will get most use anyway).
2. Introduce JSON patching, in the form of say
"application/yang-json-patch" to the spec (happy to work up some text)
3. Get back the "full" yang patch from draft -02
4. Introduce a new action/operation invoked via a parameter.

Thoughts?

Cheers.
>
>
>>
>> Cheers,
>> Wojciech.
>
>
>
> Andy
>
>>
>> >
>> > /martin
>
>