Subject: [netmod] Question on RESTCONF / Yang list creation without key value

From: Ramon Casellas <[email-masked]>
Date: Wed, 19 Jun 2019 08:37:25 +0200

Dear all,

Apologies if this is a FAQ, or a basic question but we have been 
recently involved in using RESTCONF  / YANG as a controller NBI to 
request optical connections in the photonic media layer within the TAPI 
framework and we have a doubt.

TL&DR: is it possible to create a list entry without specifying its key, 
assuming that the server can allocate such key while processing the 
request ?

For the context, the TAPI connectivity model allows a client to request 
a connectivity-service. Assume the server manages a list of 
connectivity-services (within a context) keyed by a UUID.

   grouping connectivity-context {
             list connectivity-service {
                 key 'uuid';
                 uses connectivity-service;
             }
   }

with grouping connectivity-service {
             list end-point {
                 key 'local-id';
                 min-elements 2;
                 uses connectivity-service-end-point;
             }

             leaf uuid {
                 type uuid;
            }

For historical reasons, there are two flavors: one is RPC based and the 
other one is data node based. In the RPC based approach, the RPC method 
allows the client to specify the endpoints, the server creates the 
service and replies with the details.

         rpc create-connectivity-service {
             input {
                 list end-point {
                     key 'local-id';
                     min-elements 2;
                     uses connectivity-service-end-point;
                 }
          ...
             output {
                 container service {
                     uses connectivity-service;
                 }
             }
         }

When considering deprecating the RPCs and moving towards a plain POST, 
we want to know if the client MAY not specify a uuid, as in POST to 
http://localhost:4900/restconf/data/tapi-common:context/tapi-connectivity:connectivity-context
{
     "tapi-connectivity:connectivity-service" : [
        {
           "end-point" : [
              {
               ...
              },

A particular use case is as follows: The client MAY specify a uuid when 
requesting a connectivity service
- The server MUST allocate a uuid upon creation of the list entry
- If the client provided uuid can be used, the server MUST use that UUID 
(provided there are no conflicts, other errors, etc)
- If such uuid is already in use, the server MUST reply with a failure 
(in-use, 409) or similar. The client MAY retry the operation with 
another client generated UUID.
- If the operation is successful  the server MUST reply with the 
Location header

It seems this case is somehow covered by the RPC, but when a new 
connectivity-service resource is requested through the RESTCONF Data API 
through a POST operation, MUST the client specify the key (uuid) or is 
it legal to allow the server to process the request, allocate the uuid 
in the process and return the location header?.
It is assumed that the server has all the information needed to allocate 
a uuid.

As per RFC7950

    The combined values of all the leafs specified in the key are used to
    uniquely identify a list entry.  All key leafs MUST be given values
    when a list entry is created.  Thus, any default values in the key
    leafs or their types are ignored.  Any "mandatory" statements in the
    key leafs are ignored.   A leaf that is part of the key can be of 
any built-in or
    derived type.  All key leafs in a list MUST have the same value for 
their "config"
    as the list itself.

It does not explicitly say "by the client", but it can be inferred. 
Different views are i) the server may allocate the uuid, [ as in 
https://www.w3.org/Protocols/rfc2616/rfc2616-sec9.html#sec9.5: If a 
resource has been created on the origin server, the response SHOULD be 
201 (Created) and contain an entity which describes the status of the 
request and refers to the new resource, and a Location header (see 
section 14.30) ] ensuring unique leys or ii) the uuid must be provided 
by the client

  We are also aware that with NETCONF things can be different (7.8.6.  
NETCONF <edit-config> Operations  List entries can be created, deleted, 
replaced, and modified through <edit-config>, by using the "operation" 
attribute in the list's XML  element.  In each case, the values of all 
keys are used to uniquely   identify a list entry.  If all keys are not 
specified for a list    entry, a "missing-element" error is returned.)

Thank you very much in advance

Ramon

---

From: Kent Watsen <[email-masked]>
Date: Thu, 20 Jun 2019 03:39:49 +0000

> On Jun 19, 2019, at 2:37 AM, Ramon Casellas <[email-masked]> wrote:
> 
> Dear all,
> 
> Apologies if this is a FAQ, or a basic question but we have been recently involved in using RESTCONF  / YANG as a controller NBI to request optical connections in the photonic media layer within the TAPI framework and we have a doubt.
> 
> TL&DR: is it possible to create a list entry without specifying its key, assuming that the server can allocate such key while processing the request ?

The expected answer is "no", because, as RFC 7950 Section 7.8.2 says: '''the "key" statement ... MUST be present if the list represents configuration''', and hence most tooling will expect the keys to be present in POST operations.

That said, note that the requirement is on data-at-rest and not specifically data-on-wire, so there might be wiggle-room for a server-allocated value to be inserted between receiving the POST request and updating <running>. 

However, RFC 8040 Section 4.4.1 says "the message-body MUST contain exactly one instance of the expected data resource.  The data model for the child tree is the subtree, as defined by YANG for the child resource.".  This puts a constraint on the data-on-wire, though the "is" isn't RFC 2119 language and therefore the true meaning could be debated.

Kent // contributor

---

From: Ramon Casellas <[email-masked]>
Date: Thu, 20 Jun 2019 06:01:17 +0200

On Jun 20, 2019 5:39 AM, Kent Watsen <[email-masked]> wrote:

Hi Kent

I see your point, i.e., concerning tools, but IMHO that RFC sentence refers to the Yang data model itself, and the list does contain a key statement.

However, RFC 8040 Section 4.4.1 says "the message-body MUST contain exactly one instance of the expected data resource.

On the other hand, this seems  to clearly imply that lacking the key / uuid, the post message  does not contain a fully constructed instance of the data resource.

Thanks

R