Subject: [netconf] [Technical Errata Reported] RFC8040 (6362)

From: RFC Errata System <[email-masked]>
Date: Tue, 22 Dec 2020 06:34:14 -0800 (PST)

The following errata report has been submitted for RFC8040,
"RESTCONF Protocol".

--------------------------------------
You may review the report below and at:
https://www.rfc-editor.org/errata/eid6362

--------------------------------------
Type: Technical
Reported by: Muly Ilan <[email-masked]>

Section: 4.3.

Original Text
-------------
   The client might request the response header fields for an XML
   representation of a specific "album" resource:

      GET /restconf/data/example-jukebox:jukebox/\
         library/artist=Foo%20Fighters/album=Wasting%20Light HTTP/1.1
      Host: example.com
      Accept: application/yang-data+xml

   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+xml
      Cache-Control: no-cache
      ETag: "a74eefc993a2b"
      Last-Modified: Thu, 26 Jan 2017 14:02:14 GMT

Corrected Text
--------------
   The client might request the response header fields for an XML
   representation of a specific "album" resource:

      GET /restconf/data/example-jukebox:jukebox/\
         library/artist=Foo%20Fighters/album=Wasting%20Light HTTP/1.1
      Host: example.com
      Accept: application/yang-data+xml

   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+xml
      Cache-Control: no-cache

Notes
-----
Removed the "ETag" and "Last-Modified" header fields.

According to Appendix B.3.1. :
   To retrieve only the configuration child resources, the "content"
   parameter is set to "config".  Note that the "ETag" and
   "Last-Modified" headers are only returned if the "content" parameter
   value is "config".

Instructions:
-------------
This erratum is currently posted as "Reported". If necessary, please
use "Reply All" to discuss whether it should be verified or
rejected. When a decision is reached, the verifying party  
can log in to change the status and edit the report, if necessary. 

--------------------------------------
RFC8040 (draft-ietf-netconf-restconf-18)
--------------------------------------
Title               : RESTCONF Protocol
Publication Date    : January 2017
Author(s)           : A. Bierman, M. Bjorklund, K. Watsen
Category            : PROPOSED STANDARD
Source              : Network Configuration
Area                : Operations and Management
Stream              : IETF
Verifying Party     : IESG

---

From: Andy Bierman <[email-masked]>
Date: Tue, 22 Dec 2020 06:57:40 -0800

Hi,

This Errata should be rejected.
The cited text in non-normative Appendix B.3.1 is actually wrong.
The parameter content=all can also return these fields for configuration
data.

The normative text in 3.5.2 explains what to do.

3.5.2 <https://tools.ietf.org/html/rfc8040#section-3.5.2>.  Entity-Tag

   For configuration data resources, the server SHOULD maintain a
   resource entity-tag for each resource and return the "ETag" header
   field when it is retrieved as the target resource with the GET or
   HEAD methods.  If maintained, the resource entity-tag MUST be updated
   whenever the resource or any configuration resource within the
   resource is altered.  If not maintained, then the resource entity-tag
   for the datastore MUST be used instead.

Andy

---

From: Muly Ilan <[email-masked]>
Date: Tue, 22 Dec 2020 15:06:21 +0000

Hi Andy,

You are saying that the text in Appendix B.3.1 is wrong. Understood.

Please note that there's a specific example for "content=all" in Appendix B.3.1.  In this example the "ETag" and "Last-Modified" header fields are not used.
I was looking for a well-defined behavior for all the three options of the "content" query parameter.

Thanks,

Muly

From: Andy Bierman [mailto:[email-masked]]
Sent: 22/12/2020 16:58
To: RFC Errata System <[email-masked]>
Cc: Martin Bjorklund <[email-masked]>; Kent Watsen <[email-masked]>; Warren Kumari <[email-masked]>; Robert Wilton <[email-masked]>; Kent Watsen <[email-masked]>; Mahesh Jethanandani <[email-masked]>; Muly Ilan <[email-masked]>; Netconf <[email-masked]>
Subject: Re: [Technical Errata Reported] RFC8040 (6362)

Hi,

This Errata should be rejected.
The cited text in non-normative Appendix B.3.1 is actually wrong.
The parameter content=all can also return these fields for configuration data.

3.5.2<https://eur01.safelinks.protection.outlook.com/?url=https%3A%2F%2Ftools.ietf.org%2Fhtml%2Frfc8040%23section-3.5.2&data=04%7C01%7Cmuly_i%40rad.com%7C35e8783752fa459ae98a08d8a689f57a%7Cf9047108cc2c4e4897a343fad1b3bf9d%7C1%7C0%7C637442458750543741%7CUnknown%7CTWFpbGZsb3d8eyJWIjoiMC4wLjAwMDAiLCJQIjoiV2luMzIiLCJBTiI6Ik1haWwiLCJXVCI6Mn0%3D%7C1000&sdata=7z9T58Li8GDhW2ctfforl%2BtjSz5EwWrCC6UQE6paC2Y%3D&reserved=0>.  Entity-Tag

Andy

On Tue, Dec 22, 2020 at 6:34 AM RFC Errata System <[email-masked]<mailto:[email-masked]>> wrote:
The following errata report has been submitted for RFC8040,
"RESTCONF Protocol".

--------------------------------------
You may review the report below and at:
https://www.rfc-editor.org/errata/eid6362<https://eur01.safelinks.protection.outlook.com/?url=https%3A%2F%2Fwww.rfc-editor.org%2Ferrata%2Feid6362&data=04%7C01%7Cmuly_i%40rad.com%7C35e8783752fa459ae98a08d8a689f57a%7Cf9047108cc2c4e4897a343fad1b3bf9d%7C1%7C0%7C637442458750553733%7CUnknown%7CTWFpbGZsb3d8eyJWIjoiMC4wLjAwMDAiLCJQIjoiV2luMzIiLCJBTiI6Ik1haWwiLCJXVCI6Mn0%3D%7C1000&sdata=%2BGo3kt4FmuA6g6PMoXDD1jbziLdLZpO6OerPIfiNRBU%3D&reserved=0>

--------------------------------------
Type: Technical
Reported by: Muly Ilan <[email-masked]<mailto:[email-masked]>>

Section: 4.3.

Original Text
-------------

      GET /restconf/data/example-jukebox:jukebox/\
         library/artist=Foo%20Fighters/album=Wasting%20Light HTTP/1.1
      Host: example.com<https://eur01.safelinks.protection.outlook.com/?url=http%3A%2F%2Fexample.com%2F&data=04%7C01%7Cmuly_i%40rad.com%7C35e8783752fa459ae98a08d8a689f57a%7Cf9047108cc2c4e4897a343fad1b3bf9d%7C1%7C0%7C637442458750553733%7CUnknown%7CTWFpbGZsb3d8eyJWIjoiMC4wLjAwMDAiLCJQIjoiV2luMzIiLCJBTiI6Ik1haWwiLCJXVCI6Mn0%3D%7C1000&sdata=j6Qv7qb%2Btlq6PVL1JK4l5opCHygcLLZTqPyufDyVtII%3D&reserved=0>
      Accept: application/yang-data+xml

      HTTP/1.1 200 OK

Corrected Text
--------------

      GET /restconf/data/example-jukebox:jukebox/\
         library/artist=Foo%20Fighters/album=Wasting%20Light HTTP/1.1
      Host: example.com<https://eur01.safelinks.protection.outlook.com/?url=http%3A%2F%2Fexample.com%2F&data=04%7C01%7Cmuly_i%40rad.com%7C35e8783752fa459ae98a08d8a689f57a%7Cf9047108cc2c4e4897a343fad1b3bf9d%7C1%7C0%7C637442458750563727%7CUnknown%7CTWFpbGZsb3d8eyJWIjoiMC4wLjAwMDAiLCJQIjoiV2luMzIiLCJBTiI6Ik1haWwiLCJXVCI6Mn0%3D%7C1000&sdata=FsU3K27Uav6bEaRklgGqDr11S5Yp%2FJEzebV5KyF2974%3D&reserved=0>
      Accept: application/yang-data+xml

      HTTP/1.1 200 OK

Notes
-----

Instructions:
-------------

---

From: Kent Watsen <[email-masked]>
Date: Tue, 22 Dec 2020 17:15:55 +0000

The example uses “/data”, i.e., the unified datastore, which may contain operational data.  I guess that, for /data, it could be said that any "ETag" and "Last-Modified” headers only reflect the “config true” data present, in which case Andy’s interpretation makes sense.

But this is not true for NMDA’s <operational>, where said headers likely should never be returned, even if the “content” parameter is “config”.  

For NMDA’s <running>, it seems that the headers should always be returned, even when the “content” parameter is not specified, as Andy states.  I’m assuming content=nonconfig on <running> is an error case, or at least a non-sensical case..

K.

> On Dec 22, 2020, at 9:57 AM, Andy Bierman <[email-masked]> wrote:
> 
> Hi,
> 
> On Tue, Dec 22, 2020 at 6:34 AM RFC Errata System <[email-masked] <mailto:[email-masked]>> wrote:
> https://www.rfc-editor.org/errata/eid6362 <https://www.rfc-editor.org/errata/eid6362>
> 
> Reported by: Muly Ilan <[email-masked] <mailto:[email-masked]>>
> 
> Section: 4.3.
> 
> Original Text
> -------------
>       Host: example.com <http://example.com/>
>       Host: example.com <http://example.com/>