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

[Wojciech Dec <[e-mail]>]

On 10 January 2014 14:39, Wojciech Dec <[e-mail]> wrote:
> 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.

Forgot to add one more:
5. Introduce meta-data to handle the partial update.

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