Subject: [netconf] Wrong example in RFC 8040 Section 3.1

From: Henning Rogge <[email-masked]>
Date: Thu, 23 Apr 2020 09:13:45 +0200

Hi,

I think the second example in section 3.1 "Root Resource Discovery" of
RFC 8040 is wrong (it is just the first example repeated):

> In this example, the client would use the path "/restconf" as the
>  RESTCONF root resource.
>
>   Example returning /top/restconf:

but then the example for "/.well-known/host-meta" follows.

I would expect something like in Appendix B.1.1.:

> The client may then retrieve the top-level API resource, using the
> root resource "/restconf".
>
>    GET /restconf HTTP/1.1
>    Host: example.com
>    Accept: application/yang-data+json

> The server might respond as follows:

>      HTTP/1.1 200 OK
>      Date: Thu, 26 Jan 2017 20:56:30 GMT
>      Server: example-server
>      Content-Type: application/yang-data+json
>
>      {
>        "ietf-restconf:restconf" : {
>          "data" : {},
>          "operations" : {},
>          "yang-library-version" : "2016-06-21"
>        }
>      }

Is it correct to report data/operations always with an empty
dictionary for this root query, even if there are data/operations
available?

Henning Rogge

---

From: "Per Andersson (perander)" <[email-masked]>
Date: Thu, 23 Apr 2020 08:39:20 +0000

Hi!

> From: netconf <[email-masked]> on behalf of Henning Rogge <[email-masked]>

>>          "yang-library-version" : "2016-06-21"

No, the examples are for the Root Resource Discovery, i.e. what is the
path to {+restconf} ; not for the Root Resource, i.e. accessing the actual
{+restconf} path.

Note that the examples show different values (/restconf, and
/top/restconf respectively) for {+restconf}, the RESTCONF Root
Resource.

> dictionary for this root query, even if there are data/operations

Yes, I would say it is correct even though it is not explicitly stated
in RFC 8040. The API resource is an overview of supported
functionality by the RESTCONF server.

The following statements give some support to this reasoning:

    3.3.  API Resource

        The "yang-api" YANG data template is defined using the "yang-data"
        extension in the "ietf-restconf" module, found in Section 8.  It
        specifies the structure and syntax of the conceptual child resources
        within the API resource.

    3.3.1.  {+restconf}/data

        This mandatory resource represents the combined configuration and
        state data resources that can be accessed by a client.  It cannot be
        created or deleted by the client.  The datastore resource type is
        defined in Section 3.4.

    3.3.2.  {+restconf}/operations

        This optional resource is a container that provides access to the
        data-model-specific RPC operations supported by the server.  The
        server MAY omit this resource if no data-model-specific RPC
        operations are advertised.

    3.3.3.  {+restconf}/yang-library-version

        This mandatory leaf identifies the revision date of the
        "ietf-yang-library" YANG module that is implemented by this server.
        In the example that follows, the revision date for the module version
        found in [RFC7895] is used.

Note that {+restconf}/data and {+restconf}/yang-library-version are mandatory
while {+restconf}/operations is optional. If the RESTCONF Root Resource would
also emit all data it would be very difficult to get an overvew of what the
RESTCONF server supports.

--
Per

---

From: Henning Rogge <[email-masked]>
Date: Thu, 23 Apr 2020 11:19:41 +0200

> /top/restconf respectively) for {+restconf}, the RESTCONF Root

Okay... was a little bit subtil but I think you are right that I were wrong.

I was a bit confused that there is no normative example of querying
the root resource, only one in the appendix.

> functionality by the RESTCONF server.
...
> RESTCONF server supports.

Good, that one more "done" point in my implementation...

currently I am slowly working myself through RFC8040 to extract the
examples as test cases for my code.

Henning Rogge

---

From: Kent Watsen <[email-masked]>
Date: Thu, 23 Apr 2020 16:26:46 +0000

Hi Henning,

> the root resource, only one in the appendix.

Per is correct and, yes, that section could’ve been better formatted 

> ....

I tend to agree again with Per here, though my argument rests on that the example would otherwise be invalid since, “ietf-yang-library” is required and the example doesn’t pass the “content=confg” query parameter...

Kent // co-author