tech-invite   World Map     

IETF     RFCs     Groups     SIP     ABNFs    |    3GPP     Specs     Glossaries     Architecture     IMS     UICC    |    search

RFC 8040

 
 
 

RESTCONF Protocol

Part 6 of 6, p. 105 to 137
Prev Section

 


prevText      Top      ToC       Page 105 
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      Up      ToC       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      Up      ToC       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      Up      ToC       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      Up      ToC       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      Up      ToC       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      Up      ToC       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      Up      ToC       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      Up      ToC       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      Up      ToC       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      Up      ToC       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      Up      ToC       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      Up      ToC       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      Up      ToC       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      Up      ToC       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      Up      ToC       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      Up      ToC       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      Up      ToC       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      Up      ToC       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      Up      ToC       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      Up      ToC       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      Up      ToC       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      Up      ToC       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      Up      ToC       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      Up      ToC       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      Up      ToC       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      Up      ToC       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      Up      ToC       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      Up      ToC       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      Up      ToC       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      Up      ToC       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      Up      ToC       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      Up      ToC       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