RFC 8040
RESTCONF Protocol
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
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."; }
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.";
}
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.";
}
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
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.";
}
}
}
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.";
}
}
}
}
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
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
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
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"
},
{
"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"
}
]
}
]
}
}
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>
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"
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" }
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"
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>
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>
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; } } }
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
}
]
}
}
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"
}
]
}
}
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.
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
},
{
"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
}
}
}
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" : {}
}
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.
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"
}
]
}
}
}
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"
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"
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
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%3A00ZB.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".
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.
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