added RESTCONF example

netconf-wg · Jun 24, 2024 · bc49d91 · bc49d91
1 parent 79fe56b
commit bc49d91
Showing 1 changed file with 74 additions and 41 deletions.
diff --git a/draft-ietf-netconf-restconf-trace-ctx-headers.md b/draft-ietf-netconf-restconf-trace-ctx-headers.md
@@ -3,7 +3,7 @@ docname: draft-ietf-netconf-restconf-trace-ctx-headers-latest
 title:  RESTCONF Extension to support Trace Context Headers
 abbrev: rc_trace
 category: std
-date: 2024-06-18
+date: 2024-06-24
 
 ipr: trust200902
 submissiontype: IETF
@@ -94,7 +94,7 @@ A RESTCONF server SHOULD support trace context tracestate header as defined in {
 
 The RESTCONF server SHOULD follow the "Processing Model for Working with Trace Context" as specified in {{W3C-Trace-Context}}.
 
-If the server rejects the RPC because of the trace context headers values, the server MUST return an rpc-error with the following values:
+If the server rejects the RPC because of the trace context headers, the server MAY return an rpc-error with the following values:
 
       error-tag:      operation-failed
       error-type:     protocol
@@ -104,13 +104,79 @@ If the server rejects the RPC because of the trace context headers values, the s
 
  Finally, the sx:structure defined in {{I-D.draft-rogaglia-netconf-trace-ctx-extension-03}} SHOULD be present in any error message from the server.
 
- Example of a badly formated trace context extension using {{RFC8040}} example B.2.1:
+## Trace Context header versionning
+
+This extension refers to the {{W3C-Trace-Context}} trace context capability. The W3C traceparent and trace-state headers include the notion of versions. It would be desirable for a RESTCONF client to be able to discover the one or multiple versions of these headers supported by a server. We would like to achieve this goal avoiding the deffinition of new RESTCONF capabilities for each headers' version.
+
+{{I-D.draft-rogaglia-netconf-trace-ctx-extension-03}} defines a pair YANG modules that SHOULD be included in the YANG library per {{RFC8525}} of the RESTCONF server supporting the RESTCONF Trace Context extension that will refer to the headers' supported versions. Future updates of this document could include additional YANG modules for new headers' versions.
+
+# Security Considerations
+
+There are no YANG modules specified in this document, even though the functionality described herein relates to the network management protocol RESTCONF [RFC8040].  This is because the only functionality described are additional HTTP headers, and those cannot be described using YANG.There are still some security considerations worth mentioning, however.
+
+The traceparent and tracestate headers make it easier to track the flow of requests and their downstream effect on other systems.  This is indeed the whole point with these headers.  This knowledge could also be of use to bad actors that are working to build a map of the managed network.
+
+The lowest RESTCONF layer is HTTPS, and the mandatory-to-implement secure transport is TLS [RFC8446].
+
+The Network Configuration Access Control Model (NACM) [RFC8341] provides the means to restrict access for particular NETCONF or RESTCONF users to a preconfigured subset of all available NETCONF or RESTCONF protocol operations and content.
+
+All privacy and security consideration in {{W3C-Trace-Context}} apply to this document.
+
+# IANA Considerations
+
+This document has no IANA actions.
+
+# Acknowledgments
+
+The authors would like to acknowledge the valuable implementation feedback from Christian Rennerskog and Per Andersson.  Many thanks to Raul Rivas Felix, Alexander Stoklasa, Luca Relandini and Erwin Vrolijk for their help with the demos regarding integrations.  The help and support from Jean Quilbeuf and Benoît Claise has also been invaluable to this work.
+
+--- back
+
+# Example RESTCONF calls
+
+All examples from {{RFC8040}} Appendix B could be recreated in this seciton by adding the new header described in this document. We selected one example from that document as reference.
+
+## Successful creation New Data Resources (from section B.2.1 in {{RFC8040}})
+
+To create a new "artist" resource within the "library" resource, the client might send the following request:
+
+      POST /restconf/data/example-jukebox:jukebox/library HTTP/1.1
+      Host: example.com
+      Content-Type: application/yang-data+json
+      traceparent: 00-405062f633be64ee006089dfca95a153-e021f9e263aad8e2-01
+      tracestate: vendorname1=opaqueValue1,vendorname2=opaqueValue2
+
+      {
+        "example-jukebox:artist" : [
+          {
+            "name" : "Foo Fighters"
+          }
+        ]
+      }
+
+If the resource is created, the server might respond as follows:
+
+      HTTP/1.1 201 Created
+      Date: Thu, 26 Jan 2017 20:56:30 GMT
+      Server: example-server
+      Location: https://example.com/restconf/data/\
+          example-jukebox:jukebox/library/artist=Foo%20Fighters
+      Last-Modified: Thu, 26 Jan 2017 20:56:30 GMT
+      ETag: "b3830f23a4c"
+      traceparent: 00-405062f633be64ee006089dfca95a153-e021f9e263aad8e2-01
+      tracestate: vendorname1=opaqueValue1,vendorname2=opaqueValue2
+
+## Unsuccessful creation New Data Resources (from section B.2.1 in {{RFC8040}})
+
+{{W3C-Trace-Context}} specifies that vendor MAY validate the tracestate header and that invalid headers MAY be discarded. In Section {Errors handling}, it is stated that servers MAY return an error. Let's assume that is our implementation.
+
+Example of a badly formated tracestate header using {{RFC8040}} example B.2.1, which by following :
 
       POST /restconf/data/example-jukebox:jukebox/library HTTP/1.1
       Host: example.com
       Content-Type: application/yang-data+json
-      traceparent: SomeBadFormatHere
-      tracestate: OrSomeBadFormatHere
+      traceparent: 00-405062f633be64ee006089dfca95a153-e021f9e263aad8e2-01
+      tracestate: SomeBadFormatHere
 
       {
         "example-jukebox:artist" : [
@@ -136,7 +202,7 @@ And the expected error message:
              "error-message" :
              "OTLP traceparent attribute incorrectly formatted",
              "error-info": {
-               "ietf-netconf-otlp-context:meta-name" : "traceparent",
+               "ietf-netconf-otlp-context:meta-name" : "tracestate",
                "ietf-netconf-otlp-context:meta-value" :
                "SomeBadFormatHere",
                "ietf-netconf-otlp-context:error-type" :
@@ -147,52 +213,19 @@ And the expected error message:
        }
      }
 
-## Trace Context header versionning
-
-This extension refers to the {{W3C-Trace-Context}} trace context capability. The W3C traceparent and trace-state headers include the notion of versions. It would be desirable for a RESTCONF client to be able to discover the one or multiple versions of these headers supported by a server. We would like to achieve this goal avoiding the deffinition of new RESTCONF capabilities for each headers' version.
-
-{{I-D.draft-rogaglia-netconf-trace-ctx-extension-03}} defines a pair YANG modules that SHOULD be included in the YANG library per {{RFC8525}} of the RESTCONF server supporting the RESTCONF Trace Context extension that will refer to the headers' supported versions. Future updates of this document could include additional YANG modules for new headers' versions.
-
-# Security Considerations
-
-There are no YANG modules specified in this document, even though the functionality described herein relates to the network management protocol RESTCONF [RFC8040].  This is because the only functionality described are additional HTTP headers, and those cannot be described using YANG.There are still some security considerations worth mentioning, however.
-
-The traceparent and tracestate headers make it easier to track the flow of requests and their downstream effect on other systems.  This is indeed the whole point with these headers.  This knowledge could also be of use to bad actors that are working to build a map of the managed network.
-
-The lowest RESTCONF layer is HTTPS, and the mandatory-to-implement secure transport is TLS [RFC8446].
-
-The Network Configuration Access Control Model (NACM) [RFC8341] provides the means to restrict access for particular NETCONF or RESTCONF users to a preconfigured subset of all available NETCONF or RESTCONF protocol operations and content.
-
-# IANA Considerations
-
-This document has no IANA actions.
-
-# Acknowledgments
-
-The authors would like to acknowledge the valuable implementation feedback from Christian Rennerskog and Per Andersson.  Many thanks to Raul Rivas Felix, Alexander Stoklasa, Luca Relandini and Erwin Vrolijk for their help with the demos regarding integrations.  The help and support from Jean Quilbeuf and Benoît Claise has also been invaluable to this work.
-
---- back
-
-# Example RESTCONF calls
-
-TBD
-
 # Changes (to be deleted by RFC Editor)
 
 ## From version 00 to -01
 - Added Security considerations
 - Added Acknowledgements
 - Added several Normative references
 - Added links to latest document on github
+- Added RESTCONF example for success and error
+- Modified Error Handling to reflect better W3C alignment based on implementation feedback
 
 ## From version 00 to draft-ietf-netconf-restconf-trace-ctx-headers-00
 - Adopted by NETCONF WG
 - Moved repository to NETCONF WG
 - Changed build system to use martinthomson's excellent framework
 - Ran make fix-lint to remove white space at EOL etc.
 - Added this change note. No other content changes.
-
-
-# TO DO List (to be deleted by RFC Editor)
-
-- Example RESTCONF Calls