Tech-invite3GPPspaceIETF RFCsSIP
93929190898887868584838281807978777675747372717069686766656463626160595857565554535251504948474645444342414039383736353433323130292827262524232221201918171615141312111009080706050403020100
in Index   Prev   Next

RFC 8040

RESTCONF Protocol

Pages: 137
Proposed Standard
Errata
Part 6 of 6 – Pages 105 to 137
First   Prev   None

Top   ToC   RFC8040 - Page 105   prevText

Appendix A. Example YANG Module

The example YANG module used in this document represents a simple media jukebox interface. YANG tree diagram for the "example-jukebox" module: +--rw jukebox! +--rw library | +--rw artist* [name] | | +--rw name string | | +--rw album* [name] | | +--rw name string | | +--rw genre? identityref | | +--rw year? uint16 | | +--rw admin | | | +--rw label? string | | | +--rw catalogue-number? string | | +--rw song* [name] | | +--rw name string | | +--rw location string | | +--rw format? string | | +--rw length? uint32 | +--ro artist-count? uint32 | +--ro album-count? uint32 | +--ro song-count? uint32 +--rw playlist* [name] | +--rw name string | +--rw description? string | +--rw song* [index] | +--rw index uint32 | +--rw id instance-identifier +--rw player +--rw gap? decimal64 rpcs: +---x play +--ro input +--ro playlist string +--ro song-number uint32
Top   ToC   RFC8040 - Page 106

A.1. "example-jukebox" YANG Module

module example-jukebox { namespace "http://example.com/ns/example-jukebox"; prefix "jbox"; organization "Example, Inc."; contact "support at example.com"; description "Example Jukebox Data Model Module."; revision "2016-08-15" { description "Initial version."; reference "example.com document 1-4673."; } identity genre { description "Base for all genre types."; } // abbreviated list of genre classifications identity alternative { base genre; description "Alternative music."; } identity blues { base genre; description "Blues music."; } identity country { base genre; description "Country music."; } identity jazz { base genre; description "Jazz music."; } identity pop { base genre; description "Pop music."; }
Top   ToC   RFC8040 - Page 107
      identity rock {
        base genre;
        description
          "Rock music.";
      }

      container jukebox {
        presence
          "An empty container indicates that the jukebox
           service is available.";

        description
          "Represents a 'jukebox' resource, with a library, playlists,
           and a 'play' operation.";

        container library {

          description
            "Represents the 'jukebox' library resource.";

          list artist {
            key name;
            description
              "Represents one 'artist' resource within the
               'jukebox' library resource.";

            leaf name {
              type string {
                length "1 .. max";
              }
              description
                "The name of the artist.";
            }

            list album {
              key name;
              description
                "Represents one 'album' resource within one
                 'artist' resource, within the jukebox library.";

              leaf name {
                type string {
                  length "1 .. max";
                }
                description
                  "The name of the album.";
              }
Top   ToC   RFC8040 - Page 108
              leaf genre {
                type identityref { base genre; }
                description
                  "The genre identifying the type of music on
                   the album.";
              }

              leaf year {
                type uint16 {
                  range "1900 .. max";
                }
                description
                  "The year the album was released.";
              }

              container admin {
                description
                  "Administrative information for the album.";

                leaf label {
                  type string;
                  description
                    "The label that released the album.";
                }
                leaf catalogue-number {
                  type string;
                  description
                    "The album's catalogue number.";
                }
              }

              list song {
                key name;
                description
                  "Represents one 'song' resource within one
                   'album' resource, within the jukebox library.";

                leaf name {
                  type string {
                     length "1 .. max";
                  }
                  description
                    "The name of the song.";
                }
Top   ToC   RFC8040 - Page 109
                leaf location {
                  type string;
                  mandatory true;
                  description
                    "The file location string of the
                     media file for the song.";
                }
                leaf format {
                  type string;
                  description
                    "An identifier string for the media type
                     for the file associated with the
                     'location' leaf for this entry.";
                }
                leaf length {
                  type uint32;
                  units "seconds";
                  description
                    "The duration of this song in seconds.";
                }
              }   // end list 'song'
            }   // end list 'album'
          }  // end list 'artist'

          leaf artist-count {
             type uint32;
             units "artists";
             config false;
             description
               "Number of artists in the library.";
          }
          leaf album-count {
             type uint32;
             units "albums";
             config false;
             description
               "Number of albums in the library.";
          }
          leaf song-count {
             type uint32;
             units "songs";
             config false;
             description
               "Number of songs in the library.";
          }
        }  // end library
Top   ToC   RFC8040 - Page 110
        list playlist {
          key name;
          description
            "Example configuration data resource.";

          leaf name {
            type string;
            description
              "The name of the playlist.";
          }
          leaf description {
            type string;
            description
              "A comment describing the playlist.";
          }
          list song {
            key index;
            ordered-by user;

            description
              "Example nested configuration data resource.";

            leaf index {    // not really needed
              type uint32;
              description
                "An arbitrary integer index for this playlist song.";
            }
            leaf id {
              type instance-identifier;
              mandatory true;
              description
                "Song identifier.  Must identify an instance of
                 /jukebox/library/artist/album/song/name.";
            }
          }
        }
Top   ToC   RFC8040 - Page 111
        container player {
          description
            "Represents the jukebox player resource.";

          leaf gap {
            type decimal64 {
              fraction-digits 1;
              range "0.0 .. 2.0";
            }
            units "tenths of seconds";
            description
              "Time gap between each song.";
          }
        }
      }

      rpc play {
        description
          "Control function for the jukebox player.";
        input {
          leaf playlist {
            type string;
            mandatory true;
            description
              "The playlist name.";
          }
          leaf song-number {
            type uint32;
            mandatory true;
            description
              "Song number in playlist to play.";
          }
        }
      }
   }
Top   ToC   RFC8040 - Page 112

Appendix B. RESTCONF Message Examples

The examples within this document use the normative YANG module "ietf-restconf" as defined in Section 8 and the non-normative example YANG module "example-jukebox" as defined in Appendix A.1. This section shows some typical RESTCONF message exchanges.

B.1. Resource Retrieval Examples

B.1.1. Retrieve the Top-Level API Resource

The client starts by retrieving the RESTCONF root resource: GET /.well-known/host-meta HTTP/1.1 Host: example.com Accept: application/xrd+xml
Top   ToC   RFC8040 - Page 113
   The server might respond as follows:

      HTTP/1.1 200 OK
      Content-Type: application/xrd+xml
      Content-Length: nnn

      <XRD xmlns='http://docs.oasis-open.org/ns/xri/xrd-1.0'>
          <Link rel='restconf' href='/restconf'/>
      </XRD>

   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"
        }
      }

   To request that the response content be encoded in XML, the "Accept"
   header can be used, as in this example request:

      GET /restconf HTTP/1.1
      Host: example.com
      Accept: application/yang-data+xml
Top   ToC   RFC8040 - Page 114
   The server will return the same conceptual data either way, which
   might be as follows:

      HTTP/1.1 200 OK
      Date: Thu, 26 Jan 2017 20:56:30 GMT
      Server: example-server
      Cache-Control: no-cache
      Content-Type: application/yang-data+xml

      <restconf xmlns="urn:ietf:params:xml:ns:yang:ietf-restconf">
        <data/>
        <operations/>
        <yang-library-version>2016-06-21</yang-library-version>
      </restconf>

B.1.2. Retrieve the Server Module Information

It is possible that the YANG library module will change over time. The client can retrieve the revision date of the "ietf-yang-library" module supported by the server from the API resource, as described in the previous section. In this example, the client is retrieving the module information from the server in JSON format: GET /restconf/data/ietf-yang-library:modules-state HTTP/1.1 Host: example.com Accept: application/yang-data+json
Top   ToC   RFC8040 - Page 115
   The server might respond as follows:

      HTTP/1.1 200 OK
      Date: Thu, 26 Jan 2017 20:56:30 GMT
      Server: example-server
      Cache-Control: no-cache
      Last-Modified: Thu, 26 Jan 2017 14:00:14 GMT
      Content-Type: application/yang-data+json

      {
        "ietf-yang-library:modules-state" : {
          "module-set-id" : "5479120c17a619545ea6aff7aa19838b036ebbd7",
          "module" : [
            {
              "name" : "foo",
              "revision" : "2012-01-02",
              "schema" : "https://example.com/modules/foo/2012-01-02",
              "namespace" : "http://example.com/ns/foo",
              "feature" : [ "feature1", "feature2" ],
              "deviation" : [
                {
                  "name" : "foo-dev",
                  "revision" : "2012-02-16"
                }
              ],
              "conformance-type" : "implement"
            },
            {
              "name" : "ietf-yang-library",
              "revision" : "2016-06-21",
              "schema" : "https://example.com/modules/\
                ietf-yang-library/2016-06-21",
              "namespace" :
                "urn:ietf:params:xml:ns:yang:ietf-yang-library",
              "conformance-type" : "implement"
            },
            {
              "name" : "foo-types",
              "revision" : "2012-01-05",
              "schema" :
                "https://example.com/modules/foo-types/2012-01-05",
              "namespace" : "http://example.com/ns/foo-types",
              "conformance-type" : "import"
            },
Top   ToC   RFC8040 - Page 116
            {
              "name" : "bar",
              "revision" : "2012-11-05",
              "schema" : "https://example.com/modules/bar/2012-11-05",
              "namespace" : "http://example.com/ns/bar",
              "feature" : [ "bar-ext" ],
              "conformance-type" : "implement",
              "submodule" : [
                {
                  "name" : "bar-submod1",
                  "revision" : "2012-11-05",
                  "schema" :
                   "https://example.com/modules/bar-submod1/2012-11-05"
                },
                {
                  "name" : "bar-submod2",
                  "revision" : "2012-11-05",
                  "schema" :
                   "https://example.com/modules/bar-submod2/2012-11-05"
                }
              ]
            }
          ]
        }
      }
Top   ToC   RFC8040 - Page 117

B.1.3. Retrieve the Server Capability Information

In this example, the client is retrieving the capability information from the server in XML format, and the server supports all of the RESTCONF query parameters, plus one vendor parameter: GET /restconf/data/ietf-restconf-monitoring:restconf-state/\ capabilities 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 Cache-Control: no-cache Last-Modified: Thu, 26 Jan 2017 16:00:14 GMT Content-Type: application/yang-data+xml <capabilities xmlns="urn:ietf:params:xml:ns:yang:ietf-restconf-monitoring"> <capability>\ urn:ietf:params:restconf:capability:defaults:1.0?\ basic-mode=explicit\ </capability> <capability>\ urn:ietf:params:restconf:capability:with-defaults:1.0\ </capability> <capability>\ urn:ietf:params:restconf:capability:depth:1.0\ </capability> <capability>\ urn:ietf:params:restconf:capability:fields:1.0\ </capability> <capability>\ urn:ietf:params:restconf:capability:filter:1.0\ </capability> <capability>\ urn:ietf:params:restconf:capability:start-time:1.0\ </capability> <capability>\ urn:ietf:params:restconf:capability:stop-time:1.0\ </capability> <capability>\ http://example.com/capabilities/myparam\ </capability> </capabilities>
Top   ToC   RFC8040 - Page 118

B.2. Data Resource and Datastore Resource Examples

B.2.1. Create New Data Resources

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 { "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"
Top   ToC   RFC8040 - Page 119
   To create a new "album" resource for this artist within the "jukebox"
   resource, the client might send the following request:

      POST /restconf/data/example-jukebox:jukebox/\
          library/artist=Foo%20Fighters HTTP/1.1
      Host: example.com
      Content-Type: application/yang-data+xml

      <album xmlns="http://example.com/ns/example-jukebox">
        <name>Wasting Light</name>
        <year>2011</year>
      </album>

   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/\
          album=Wasting%20Light
      Last-Modified: Thu, 26 Jan 2017 20:56:30 GMT
      ETag: "b8389233a4c"

B.2.2. Detect Datastore Resource Entity-Tag Change

In this example, the server just supports the datastore last-changed timestamp. Assume that the client has cached the "Last-Modified" header from the response to the previous request. This value is used as in the "If-Unmodified-Since" header in the following request to patch an "album" list entry with a key value of "Wasting Light". Only the "genre" field is being updated. PATCH /restconf/data/example-jukebox:jukebox/\ library/artist=Foo%20Fighters/album=Wasting%20Light/\ genre HTTP/1.1 Host: example.com If-Unmodified-Since: Thu, 26 Jan 2017 20:56:30 GMT Content-Type: application/yang-data+json { "example-jukebox:genre" : "example-jukebox:alternative" }
Top   ToC   RFC8040 - Page 120
   In this example, the datastore resource has changed since the time
   specified in the "If-Unmodified-Since" header.  The server might
   respond as follows:

      HTTP/1.1 412 Precondition Failed
      Date: Thu, 26 Jan 2017 20:56:30 GMT
      Server: example-server
      Last-Modified: Thu, 26 Jan 2017 19:41:00 GMT
      ETag: "b34aed893a4c"
Top   ToC   RFC8040 - Page 121

B.2.3. Edit a Datastore Resource

In this example, assume that there is a top-level data resource named "system" from the example-system module, and this container has a child leaf called "enable-jukebox-streaming": container system { leaf enable-jukebox-streaming { type boolean; } } In this example, PATCH is used by the client to modify two top-level resources at once, in order to enable jukebox streaming and add an "album" sub-resource to each of two "artist" resources: PATCH /restconf/data HTTP/1.1 Host: example.com Content-Type: application/yang-data+xml <data xmlns="urn:ietf:params:xml:ns:yang:ietf-restconf"> <system xmlns="http://example.com/ns/example-system"> <enable-jukebox-streaming>true</enable-jukebox-streaming> </system> <jukebox xmlns="http://example.com/ns/example-jukebox"> <library> <artist> <name>Foo Fighters</name> <album> <name>One by One</name> <year>2012</year> </album> </artist> <artist> <name>Nick Cave and the Bad Seeds</name> <album> <name>Tender Prey</name> <year>1988</year> </album> </artist> </library> </jukebox> </data>
Top   ToC   RFC8040 - Page 122

B.2.4. Replace a Datastore Resource

In this example, the entire configuration datastore contents are being replaced. Any child nodes not present in the <data> element but present in the server will be deleted. PUT /restconf/data HTTP/1.1 Host: example.com Content-Type: application/yang-data+xml <data xmlns="urn:ietf:params:xml:ns:yang:ietf-restconf"> <jukebox xmlns="http://example.com/ns/example-jukebox"> <library> <artist> <name>Foo Fighters</name> <album> <name>One by One</name> <year>2012</year> </album> </artist> <artist> <name>Nick Cave and the Bad Seeds</name> <album> <name>Tender Prey</name> <year>1988</year> </album> </artist> </library> </jukebox> </data>

B.2.5. Edit a Data Resource

In this example, the client modifies one data node by adding an "album" sub-resource by sending a PATCH for the data resource: PATCH /restconf/data/example-jukebox:jukebox/library/\ artist=Nick%20Cave%20and%20the%20Bad%20Seeds HTTP/1.1 Host: example.com Content-Type: application/yang-data+xml <artist xmlns="http://example.com/ns/example-jukebox"> <name>Nick Cave and the Bad Seeds</name> <album> <name>The Good Son</name> <year>1990</year> </album> </artist>
Top   ToC   RFC8040 - Page 123

B.3. Query Parameter Examples

B.3.1. "content" Parameter

The "content" parameter is used to select the types of data child resources (configuration and/or non-configuration) that are returned by the server for a GET method request. In this example, a simple YANG list is used that has configuration and non-configuration child resources. container events { list event { key name; leaf name { type string; } leaf description { type string; } leaf event-count { type uint32; config false; } } }
Top   ToC   RFC8040 - Page 124
   Example 1: content=all

   To retrieve all of the child resources, the "content" parameter is
   set to "all", or omitted, since this is the default value.  The
   client might send the following:

      GET /restconf/data/example-events:events?\
          content=all 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
      Cache-Control: no-cache
      Content-Type: application/yang-data+json

      {
        "example-events:events" : {
          "event" : [
            {
              "name" : "interface-up",
              "description" : "Interface up notification count",
              "event-count" : 42
            },
            {
              "name" : "interface-down",
              "description" : "Interface down notification count",
              "event-count" : 4
            }
          ]
        }
      }
Top   ToC   RFC8040 - Page 125
   Example 2: content=config

   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".

      GET /restconf/data/example-events:events?\
          content=config 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
      Last-Modified: Thu, 26 Jan 2017 16:45:20 GMT
      ETag: "eeeada438af"
      Cache-Control: no-cache
      Content-Type: application/yang-data+json

      {
        "example-events:events" : {
          "event" : [
            {
              "name" : "interface-up",
              "description" : "Interface up notification count"
            },
            {
              "name" : "interface-down",
              "description" : "Interface down notification count"
            }
          ]
        }
      }
Top   ToC   RFC8040 - Page 126
   Example 3: content=nonconfig

   To retrieve only the non-configuration child resources, the "content"
   parameter is set to "nonconfig".  Note that configuration ancestors
   (if any) and list key leafs (if any) are also returned.  The client
   might send the following:

      GET /restconf/data/example-events:events?\
         content=nonconfig 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
      Cache-Control: no-cache
      Content-Type: application/yang-data+json

      {
        "example-events:events" : {
          "event" : [
            {
              "name" : "interface-up",
              "event-count" : 42
            },
            {
              "name" : "interface-down",
              "event-count" : 4
            }
          ]
        }
      }

B.3.2. "depth" Parameter

The "depth" parameter is used to limit the number of levels of child resources that are returned by the server for a GET method request. The "depth" parameter starts counting levels at the level of the target resource that is specified, so that a depth level of "1" includes just the target resource level itself. A depth level of "2" includes the target resource level and its child nodes.
Top   ToC   RFC8040 - Page 127
   This example shows how different values of the "depth" parameter
   would affect the reply content for the retrieval of the top-level
   "jukebox" data resource.

   Example 1: depth=unbounded

   To retrieve all of the child resources, the "depth" parameter is not
   present or is set to the default value "unbounded".

      GET /restconf/data/example-jukebox:jukebox?\
          depth=unbounded 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
      Cache-Control: no-cache
      Content-Type: application/yang-data+json

      {
        "example-jukebox:jukebox" : {
          "library" : {
            "artist" : [
              {
                "name" : "Foo Fighters",
                "album" : [
                  {
                    "name" : "Wasting Light",
                    "genre" : "example-jukebox:alternative",
                    "year" : 2011,
                    "song" : [
                      {
                        "name" : "Wasting Light",
                        "location" :
                          "/media/foo/a7/wasting-light.mp3",
                        "format" : "MP3",
                        "length" : 286
                      },
Top   ToC   RFC8040 - Page 128
                      {
                        "name" : "Rope",
                        "location" : "/media/foo/a7/rope.mp3",
                        "format" : "MP3",
                        "length" : 259
                      }
                    ]
                  }
                ]
              }
            ]
          },
          "playlist" : [
            {
              "name" : "Foo-One",
              "description" : "example playlist 1",
              "song" : [
                {
                  "index" : 1,
                  "id" : "/example-jukebox:jukebox/library\
                     /artist[name='Foo Fighters']\
                     /album[name='Wasting Light']\
                     /song[name='Rope']"
                },
                {
                  "index" : 2,
                  "id" : "/example-jukebox:jukebox/library\
                     /artist[name='Foo Fighters']\
                     /album[name='Wasting Light']\
                     /song[name='Bridge Burning']"
                }
              ]
            }
          ],
          "player" : {
            "gap" : 0.5
          }
        }
      }
Top   ToC   RFC8040 - Page 129
   Example 2: depth=1

   To determine if one or more resource instances exist for a given
   target resource, the value "1" is used.

      GET /restconf/data/example-jukebox:jukebox?depth=1 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
      Cache-Control: no-cache
      Content-Type: application/yang-data+json

      {
        "example-jukebox:jukebox" : {}
      }
Top   ToC   RFC8040 - Page 130
   Example 3: depth=3

   To limit the depth level to the target resource plus two child
   resource layers, the value "3" is used.

      GET /restconf/data/example-jukebox:jukebox?depth=3 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
      Cache-Control: no-cache
      Content-Type: application/yang-data+json

      {
        "example-jukebox:jukebox" : {
          "library" : {
            "artist" : {}
          },
          "playlist" : [
            {
              "name" : "Foo-One",
              "description" : "example playlist 1",
              "song" : {}
            }
          ],
          "player" : {
            "gap" : 0.5
          }
        }
      }

B.3.3. "fields" Parameter

In this example, the client is retrieving the datastore resource in JSON format, but retrieving only the "modules-state/module" list, and only the "name" and "revision" nodes from each list entry. Note that the top node returned by the server matches the target resource node (which is "data" in this example). The "module-set-id" leaf is not returned because it is not selected in the fields expression.
Top   ToC   RFC8040 - Page 131
      GET /restconf/data?fields=ietf-yang-library:modules-state/\
          module(name;revision) 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:data" : {
          "ietf-yang-library:modules-state" : {
            "module" : [
              {
                "name" : "example-jukebox",
                "revision" : "2016-08-15"
              },
              {
                "name" : "ietf-inet-types",
                "revision" : "2013-07-15"
              },
              {
                "name" : "ietf-restconf-monitoring",
                "revision" : "2017-01-26"
              },
              {
                "name" : "ietf-yang-library",
                "revision" : "2016-06-21"
              },
              {
                "name" : "ietf-yang-types",
                "revision" : "2013-07-15"
              }
            ]
          }
        }
      }
Top   ToC   RFC8040 - Page 132

B.3.4. "insert" Parameter

In this example, a new first song entry in the "Foo-One" playlist is being created. Request from client: POST /restconf/data/example-jukebox:jukebox/\ playlist=Foo-One?insert=first HTTP/1.1 Host: example.com Content-Type: application/yang-data+json { "example-jukebox:song" : [ { "index" : 1, "id" : "/example-jukebox:jukebox/library\ /artist[name='Foo Fighters']\ /album[name='Wasting Light']\ /song[name='Rope']" } ] } Response from server: HTTP/1.1 201 Created Date: Thu, 26 Jan 2017 20:56:30 GMT Server: example-server Last-Modified: Thu, 26 Jan 2017 20:56:30 GMT Location: https://example.com/restconf/data/\ example-jukebox:jukebox/playlist=Foo-One/song=1 ETag: "eeeada438af"
Top   ToC   RFC8040 - Page 133

B.3.5. "point" Parameter

In this example, the client is inserting a new song entry in the "Foo-One" playlist after the first song. Request from client: POST /restconf/data/example-jukebox:jukebox/\ playlist=Foo-One?insert=after&point=\ %2Fexample-jukebox%3Ajukebox\ %2Fplaylist%3DFoo-One%2Fsong%3D1 HTTP/1.1 Host: example.com Content-Type: application/yang-data+json { "example-jukebox:song" : [ { "index" : 2, "id" : "/example-jukebox:jukebox/library\ /artist[name='Foo Fighters']\ /album[name='Wasting Light']\ /song[name='Bridge Burning']" } ] } Response from server: HTTP/1.1 201 Created Date: Thu, 26 Jan 2017 20:56:30 GMT Server: example-server Last-Modified: Thu, 26 Jan 2017 20:56:30 GMT Location: https://example.com/restconf/data/\ example-jukebox:jukebox/playlist=Foo-One/song=2 ETag: "abcada438af"
Top   ToC   RFC8040 - Page 134

B.3.6. "filter" Parameter

The following URIs show some examples of notification filter specifications: // filter = /event/event-class='fault' GET /streams/NETCONF?filter=%2Fevent%2Fevent-class%3D'fault' // filter = /event/severity<=4 GET /streams/NETCONF?filter=%2Fevent%2Fseverity%3C%3D4 // filter = /linkUp|/linkDown GET /streams/SNMP?filter=%2FlinkUp%7C%2FlinkDown // filter = /*/reporting-entity/card!='Ethernet0' GET /streams/NETCONF?\ filter=%2F*%2Freporting-entity%2Fcard%21%3D'Ethernet0' // filter = /*/email-addr[contains(.,'company.com')] GET /streams/critical-syslog?\ filter=%2F*%2Femail-addr[contains(.%2C'company.com')] // Note: The module name is used as the prefix. // filter = (/example-mod:event1/name='joe' and // /example-mod:event1/status='online') GET /streams/NETCONF?\ filter=(%2Fexample-mod%3Aevent1%2Fname%3D'joe'%20and\ %20%2Fexample-mod%3Aevent1%2Fstatus%3D'online') // To get notifications from just two modules (e.g., m1 + m2) // filter=(/m1:* or /m2:*) GET /streams/NETCONF?filter=(%2Fm1%3A*%20or%20%2Fm2%3A*)

B.3.7. "start-time" Parameter

The following URI shows an example of the "start-time" query parameter: // start-time = 2014-10-25T10:02:00Z GET /streams/NETCONF?start-time=2014-10-25T10%3A02%3A00Z
Top   ToC   RFC8040 - Page 135

B.3.8. "stop-time" Parameter

The following URI shows an example of the "stop-time" query parameter: // start-time = 2014-10-25T10:02:00Z // stop-time = 2014-10-25T12:31:00Z GET /mystreams/NETCONF?start-time=2014-10-25T10%3A02%3A00Z\ &stop-time=2014-10-25T12%3A31%3A00Z

B.3.9. "with-defaults" Parameter

Assume that the server implements the module "example" defined in Appendix A.1 of [RFC6243], and assume that the server's datastore is as defined in Appendix A.2 of [RFC6243]. If the server's "basic-mode" parameter in the "defaults" protocol capability URI (Section 9.1.2) is "trim", the following request for interface "eth1" might be as follows: Without query parameter: GET /restconf/data/example:interfaces/interface=eth1 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 { "example:interface" : [ { "name" : "eth1", "status" : "up" } ] } Note that the "mtu" leaf is missing because it is set to the default "1500", and the server's default-handling "basic-mode" parameter is "trim".
Top   ToC   RFC8040 - Page 136
   With query parameter:

      GET /restconf/data/example:interfaces/interface=eth1\
          ?with-defaults=report-all 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

      {
        "example:interface" : [
          {
            "name" : "eth1",
            "mtu" : 1500,
            "status" : "up"
          }
        ]
      }

   Note that the server returns the "mtu" leaf because the "report-all"
   mode was requested with the "with-defaults" query parameter.
Top   ToC   RFC8040 - Page 137

Acknowledgements

The authors would like to thank the following people for their contributions to this document: Ladislav Lhotka, Juergen Schoenwaelder, Rex Fernando, Robert Wilton, and Jonathan Hansford. The authors would like to thank the following people for their excellent technical reviews of this document: Mehmet Ersue, Mahesh Jethanandani, Qin Wu, Joe Clarke, Bert Wijnen, Ladislav Lhotka, Rodney Cummings, Frank Xialiang, Tom Petch, Robert Sparks, Balint Uveges, Randy Presuhn, Sue Hares, Mark Nottingham, Benoit Claise, Dale Worley, and Lionel Morand. Contributions to this material by Andy Bierman are based upon work supported by the United States Army, Space & Terrestrial Communications Directorate (S&TCD) under Contract No. W15P7T-13-C-A616. Any opinions, findings, and conclusions or recommendations expressed in this material are those of the author(s) and do not necessarily reflect the views of the S&TCD.

Authors' Addresses

Andy Bierman YumaWorks Email: andy@yumaworks.com Martin Bjorklund Tail-f Systems Email: mbj@tail-f.com Kent Watsen Juniper Networks Email: kwatsen@juniper.net