Chapter 21. The REST API

If a resource only needs to be outlined, the shallow query parameter can be used on the GET request.

GET /running/sys?shallow

<sys xmlns="http://example.com/router" 
xmlns:y="http://tail-f.com/ns/rest"  
xmlns:r="http://example.com/router">
  <interfaces/>
  <routes/>
  <syslog/>
  <ntp/>
  <dns/>
</sys>

On the other hand, if the full subtree under a resource is required, the deep query parameter can be used on the GET request.

GET /running/sys/interfaces/interface?deep

<collection xmlns:y="http://tail-f.com/ns/rest">
  <interface xmlns="http://example.com/router">
    <name>eth0</name>
    <unit xmlns="http://example.com/router">
      <name>0</name>
      <enabled>true</enabled>
      <status xmlns="http://example.com/router">
      </status>
      <family xmlns="http://example.com/router">
        <inet xmlns="http://example.com/router">
          <address xmlns="http://example.com/router">
            <name>192.168.1.2</name>
            <prefix-length>16</prefix-length>
          </address>
        </inet>
      </family>
    </unit>
    <unit xmlns="http://example.com/router">
      <name>1</name>
      <enabled>true</enabled>
      <status xmlns="http://example.com/router">
      </status>
      <family xmlns="http://example.com/router">
        <inet xmlns="http://example.com/router">
          <address xmlns="http://example.com/router">
            <name>192.168.1.3</name>
            <prefix-length>16</prefix-length>
          </address>
        </inet>
      </family>
    </unit>
    <unit xmlns="http://example.com/router">
      <name>2</name>
      <enabled>true</enabled>
      <description>My Vlan</description>
      <vlan-id>18</vlan-id>
      <status xmlns="http://example.com/router">
      </status>
    </unit>
  </interface>
</collection>

For more info about "deep" vs "shallow", see: Section 21.2.10, “Query Parameters”

By default, the server sends back the full representation of a resource after processing a request. For better performance, the server can be instructed to send only the nodes the client really needs in a partial response.

To request a partial response for a set of list entries, use the "offset" and "limit" query parameters to specify a limited set of entries to be returned.

For example, if we what to retrieve only 2 entries from the sys/routes/inte/route list we can issue the command:

GET /running/sys/routes/inet/route?offset=3&limit=2

<collection xmlns:y="http://tail-f.com/ns/rest">
  <route xmlns="http://example.com/router">
    <name>10.40.0.0</name>
    <prefix-length>16</prefix-length>
    <description>Route 4</description>
    <next-hop xmlns="http://example.com/router">
      <name>192.168.10.4</name>
    </next-hop>
  </route>
  <route xmlns="http://example.com/router">
    <name>10.50.0.0</name>
    <prefix-length>16</prefix-length>
    <description>Route 5</description>
    <next-hop xmlns="http://example.com/router">
      <name>192.168.10.5</name>
    </next-hop>
  </route>
</collection>

To request a filtered partial response, use the "select" query parameter to specify the nodes and subresources to be returned.

NOTE: "a/b/c;a/b/d" is equivalent to "a/b(c;d)"

The following request selects the routes name and next-hop/name nodes:

GET 
/running/sys/routes/inet/route/10.20.0.0,16?select=name;next-hop(name)

<route xmlns="http://example.com/router" 
xmlns:y="http://tail-f.com/ns/rest"  
xmlns:r="http://example.com/router">
  <name>10.20.0.0</name>
  <next-hop>
    <name>192.168.10.2</name>
  </next-hop>
</route>

Hidden nodes are described in Section 10.7, “Hidden Data”. By default, hidden nodes are not visible in the REST interface. In order to unhide hidden nodes for retrieval or editing, clients can use the query parameter "unhide". The format of the "unhide" parameter is a comma-separated list of

<groupname>[;<password>]

As an example:

unhide=extra,debug;secret

This example unhides the normal group "extra" and the password-protected group "debug" with the password "secret".

Normally, leaf nodes that are not set but has a default value are not displayed at a GET request. This behavior can be controlled by the use of the "with-defaults" query parameter. This parameter can take one of four values:

A request with the "with-defaults" query parameter without a specified value will be interpreted as "report-all".

If we make a normal GET of the "sys/ntp/server" resource. The default values are not retrieved:

GET /running/sys/ntp/server

<collection xmlns:y="http://tail-f.com/ns/rest">
  <server xmlns="http://example.com/router">
    <name>10.2.3.4</name>
    <key>2</key>
  </server>
</collection>

We can get also the default values by setting the query parameter with-defaults=report-all.

GET /running/sys/ntp/server?with-defaults=report-all

<collection xmlns:y="http://tail-f.com/ns/rest">
  <server xmlns="http://example.com/router">
    <name>10.2.3.4</name>
    <enabled>true</enabled>
    <peer>false</peer>
    <version>4</version>
    <key>2</key>
  </server>
</collection>

POST can be used to create a child resource to the resource specified by the uri. In this example we create a "route" list entry. The URI points to the parent container of the list. The payload in the POST request contain a "route" node that, at least, contain the list keys.

POST /running/sys/routes/inet
Content-Type: application/vnd.yang.data+xml

<route>
  <name>10.20.3.0</name>
  <prefix-length>24</prefix-length>
</route>

HTTP/1.1 201

When an element is successfully created the HTTP status response is 201. If the element already existed the status response is 409.

In this example we create a "multilink" presence container. The URI points to the list instance that contains the presence container, i.e the URI ends with the key(s). The payload in the POST request contain a "multilink" node that contain a value for the leaf node "group".

POST /running/sys/interfaces/serial/ppp0
Content-Type: application/vnd.yang.data+xml | egrep 
'(HTTP.*Created.*|Locat*)'

<multilink>
  <group>1</group>
</multilink>

HTTP/1.1 201 Created
Location: 
http://127.0.0.1:8008/api/running/sys/interfaces/ex:serial/ppp0/multil
ink

PUT can be used to create or replace a resource. No distinction is made in the prerequisites for PUT. If no resource existed it is created, but if it existed it is replaced. In the example, note how the URI ends with the keys.

PUT /running/sys/routes/inet/route/10.30.3.0,24
Content-Type: application/vnd.yang.data+xml

<route>
  <name>10.30.3.0</name>
  <prefix-length>24</prefix-length>
  <next-hop>
    <name>192.168.4.4</name>
    <metric>100</metric>
  </next-hop>
</route>

HTTP/1.1 201

When an element is successfully created the HTTP status response is 201. We make a GET to verify the "route" list after the PUT of the element.

GET /running/sys/routes/inet/route/10.30.3.0,24

<route xmlns="http://example.com/router" 
xmlns:y="http://tail-f.com/ns/rest"  
xmlns:r="http://example.com/router">
  <name>10.30.3.0</name>
  <prefix-length>24</prefix-length>
  <next-hop>
    <name>192.168.4.4</name>
  </next-hop>
</route>

We will now do a replace of the same "route" element.

PUT /running/sys/routes/inet/route/10.30.3.0,24
Content-Type: application/vnd.yang.data+xml

<route>
  <name>10.30.3.0</name>
  <prefix-length>24</prefix-length>
  <next-hop>
    <name>192.168.3.1</name>
    <metric>100</metric>
  </next-hop>
  <next-hop>
    <name>192.168.4.2</name>
    <metric>200</metric>
  </next-hop>
</route>

HTTP/1.1 204

We get the 204 response as the resource already existed. We can verify that the element is replaced.

GET /running/sys/routes/inet/route/10.30.3.0,24

<route xmlns="http://example.com/router" 
xmlns:y="http://tail-f.com/ns/rest"  
xmlns:r="http://example.com/router">
  <name>10.30.3.0</name>
  <prefix-length>24</prefix-length>
  <next-hop>
    <name>192.168.3.1</name>
  </next-hop>
  <next-hop>
    <name>192.168.4.2</name>
  </next-hop>
</route>

In this example we create a "multilink" presence container. The uri points to the not yet existing URI for the presence container "multilink". The payload in the PUT request contain a "multilink" node that contain a value for the leaf node 'group'.

PUT /running/sys/interfaces/serial/ppp0/multilink
Content-Type: application/vnd.yang.data+xml

<multilink>
  <group>1</group>
</multilink>

HTTP/1.1 201

Any subsequent request to the same URI will replace the content of "multilink" with the new payload. But the response code will instead be 204, since the resource already exists.

In this example we "populate" a non-presence container with subnode data. The URI points to the existing URI for the non-presence container "authentication", since a non-presence container always exist if its parent exist.

PUT /running/sys/interfaces/serial/ppp0/authentication
Content-Type: application/vnd.yang.data+xml

<authentication>
  <method>pap</method>
  <list-name>foobar</list-name>
</authentication>

HTTP/1.1 204

GET /running/sys/interfaces/serial/ppp0/authentication

<authentication xmlns="http://example.com/example-serial" 
xmlns:y="http://tail-f.com/ns/rest"  
xmlns:ex="http://example.com/example-serial"  
xmlns:r="http://example.com/router">
  <method>pap</method>
  <list-name>foobar</list-name>
</authentication>

To update an existing resource the PATCH method can be used. PATCH will not be allowed on non-existent resources. When we use PATCH the payload should only contain the data that should be modified.

PATCH /running/sys/routes/inet/route/10.30.3.0,24
Content-Type: application/vnd.yang.data+xml

<route>
  <next-hop>
    <name>192.168.5.1</name>
    <metric>400</metric>
  </next-hop>
</route>

HTTP/1.1 204

The response status 204 indicated successful update. Here we can see that a new next-hop entry has been added to the route.

GET /running/sys/routes/inet/route/10.30.3.0,24

<route xmlns="http://example.com/router" 
xmlns:y="http://tail-f.com/ns/rest"  
xmlns:r="http://example.com/router">
  <name>10.30.3.0</name>
  <prefix-length>24</prefix-length>
  <next-hop>
    <name>192.168.3.1</name>
  </next-hop>
  <next-hop>
    <name>192.168.4.2</name>
  </next-hop>
  <next-hop>
    <name>192.168.5.1</name>
  </next-hop>
</route>

PATCH can not be used to create new resources directly, since it must operate on existing resources. PATCH, in contrast to PUT, only merges the provided payload with the existing configuration, which makes it possible to create child resources within the target resource. In this example we create a "multilink" presence container. The uri points to the existing parent resource for the presence container "multilink".

PATCH /running/sys/interfaces/serial/ppp0
Content-Type: application/vnd.yang.data+xml

<serial>
  <multilink>
    <group>1</group>
  </multilink>
</serial>

HTTP/1.1 204

In this example we "populate" a non-presence container with subnode data. The URI points to the existing URI for the non-presence container "authentication", since a non-presence container always exist if its parent exist.

PATCH /running/sys/interfaces/serial/ppp0/authentication
Content-Type: application/vnd.yang.data+xml

<authentication>
  <method>eap</method>
</authentication>

HTTP/1.1 204

GET /running/sys/interfaces/serial/ppp0/authentication

<authentication xmlns="http://example.com/example-serial" 
xmlns:y="http://tail-f.com/ns/rest"  
xmlns:ex="http://example.com/example-serial"  
xmlns:r="http://example.com/router">
  <method>eap</method>
  <list-name>foobar</list-name>
</authentication>

For an ordered-by user list, the POST request can include the query parameters insert and resource.

The insert parameter indicated where the new element should be created. Legal values are:

The resource parameter contains the uri to an existing element in the list.

So we verify this functionality by first retrieving the "sys/dns/server" list:

GET /running/sys/dns

<dns xmlns="http://example.com/router" 
xmlns:y="http://tail-f.com/ns/rest"  
xmlns:r="http://example.com/router">
  <server>
    <address>10.2.3.4</address>
  </server>
</dns>

We now insert a new element before the existing element:

POST 
/running/sys/dns?insert=before&resource=/api/running/sys/dns/server/10
.2.3.4
Content-Type: application/vnd.yang.data+xml

<server>
  <address>10.1.1.2</address>
</server>

HTTP/1.1 201

We get a 201 status when successful and we verify the result by retreiving the list once again:

GET /running/sys/dns

<dns xmlns="http://example.com/router" 
xmlns:y="http://tail-f.com/ns/rest"  
xmlns:r="http://example.com/router">
  <server>
    <address>10.1.1.2</address>
  </server>
  <server>
    <address>10.2.3.4</address>
  </server>
</dns>

A resource is represented in XML as an XML element, with an XML attribute "y:self" that contains the URI for the resource. In the XML representation, every resource has an XML attribute:

y:self="..."
          

Leafs are properties of the resource. They are encoded in XML as elements.

XML namespaces must be used whenever there are multiple sibling nodes with the same local name. This only happens if a YANG module augments a node with the same name as another node in the same container or list. XML namespaces MAY always be used, even if there are no risk of a conflict.

In the JSON representation, this URI is encoded as:

"_self": "..."
          

In the representation of a list resource, the keys are always present, and encoded first.

JSON doesn't have anything similar to XML namespaces. However, we have adopted the notion defined in the Internet Draft: "Modeling JSON Text with YANG", where a <yang-module-name>:<tag> tag name is used in the JSON data to indicate the namespace. Note that it is only when the namespace changes that this notion is used.

   ...
    "foo": [
      {
        "_self": "/api/operational/x/foo/1",
        "id": 1,
        // Note: the 'card' container exist in a different namespace
        //       compared to its parent 'foo' list element. The
        //       'a' is the Yang module name where 'card' is defined
        "a:card": {
          "_self": "/api/operational/x/foo/1/a:card",
          "id": 1
        }
   ...
        

The "version" field is a string identifying the version of the REST api.

The "config" resource represents a unified configuration datastore, used to simplify resource management for the client. The underlying NETCONF datastores are used to implement the unified datastore, but the clients do not have to care about which underlying datastore to used.

The server hides all NETCONF datastore details for edit operations, such as the :candidate and :startup capabilities. When a client writes to this resource, the server performs the edits in the datastores used; if the candidate is enabled, the changes are written to the candidate, and then the candidate is committed; if the startup is enabled, the changes are written to running and running is copied to startup.

The media type of this resource is either "application/vnd.yang.datastore+xml" or "application/vnd.yang.datastore+json".

The "running" resource represents the running configuration datastore, and is present on all devices. Not all devices support direct modification to this resource.

The media type of this resource is either "application/vnd.yang.datastore+xml" or "application/vnd.yang.datastore+json".

The "startup" resource represents the startup configuration datastore. Not all devices support this resource.

The media type of this resource is "application/vnd.yang.datastore+xml" or "application/vnd.yang.datastore+json".

The "candidate" resource represents the candidate configuration datastore. Not all devices support this resource.

The media type of this resource is "application/vnd.yang.datastore+xml" or "application/vnd.yang.datastore+json".

The "operational" read-only resource represents the state data as well as the config data on the device, and is present on all devices. Note that actions defined as config false also will show up in this resource.

The media type of this resource is "application/vnd.yang.datastore+xml" or "application/vnd.yang.datastore+json".

The "transaction" resource represents a transaction datastore created by the JSON-RPC API. This allows REST API requests that read or write towards an existing transaction, without committing the transaction (this is left up to other entities e.g. the JSON-RPC API).

The media type of this resource is either "application/vnd.yang.datastore+xml" or "application/vnd.yang.datastore+json".

The "operations" container contains all operations defined with the "rpc" statement in the YANG models supported on the device.

The "rollbacks" container contains all available rollback files to be used to rollback the configuration state to an earlier incarnation.

The "logout" read-only resource is a meta-resource that always replies with 401 Unauthorized in order to aid scenarios where the REST API credentials are being cached by the HTTP client (e.g. a browser). Calling this resource will prompt for new credentials on subsequent requests to any other resource on the same realm.

In order to retrieve the representation of this resource, a client can send:

Note the use of the 'verbose' query parameter, see Section 21.2.10, “Query Parameters”.

GET /api?verbose
Application:vnd.yang.api+xml

HTTP/1.1 200 OK
Server: 
Date: Wed, 12 Aug 2015 11:38:23 GMT
Cache-Control: private, no-cache, must-revalidate, proxy-revalidate
Content-Length: 288
Content-Type: application/vnd.yang.api+xml
Vary: Accept-Encoding
Pragma: no-cache

<api xmlns="http://tail-f.com/ns/rest" 
xmlns:y="http://tail-f.com/ns/rest" y:self="/api">
  <version>0.5</version>
  <config y:self="/api/config"/>
  <running y:self="/api/running"/>
  <operational y:self="/api/operational"/>
  <operations/>
  <rollbacks y:self="/api/rollbacks"/>
</api>

In order to access a datastore through a lock, the client needs to POST to the "lock" resource. If the server is able to lock the datastore, the POST request succeeds with the status code "201 Created", and the "Location" HTTP header contains the URI to a newly created resource representing the locked datastore. To unlock the datastore, the client deletes the newly created resource using the HTTP method DELETE.

The "config" resource cannot be locked.

In the representation of a locked datastore, the "lock" operation is not available.

In order to facilitate recovery from failing clients with outstanding locks, the REST server deletes the resource representing the lock after some time of inactivity.

The media type of this resource is "application/vnd.yang.operation+xml".

In the representation of the candidate datastore, the "commit" operation is present, and can be POSTed to by the client to commit candidate to running, as described in section 8.3 in RFC 6241.

The media type of this resource is "application/vnd.yang.operation".

In the representation of the running datastore, the "copy-running-to-startup" operation is present, if the server also supports the startup datastore, and can be POSTed to by the client to copy the contents of running to startup, as described in section 8.7 in RFC 6241.

The media type of this resource is "application/vnd.yang.operation".

In the representation of the candidate datastore, the "discard-changes" operation is present, and can be POSTed to by the client to revert the candidate to the current running configuration, as described in section 8.3.4.2 in RFC 6241.

The media type of this resource is "application/vnd.yang.operation".

In the representation of the candidate datastore, the "validate" operation is present, and can be POSTed to by the client to validate the contents of the candidate, as described in section 8.6.4.1 in RFC 6241.

The media type of this resource is "application/vnd.yang.operation".

The examples in this section could instead have been performed using JSON specific mime types such as "application/vnd.yang.api+json", "application/vnd.yang.datastore+json" and "application/vnd.yang.data+json".

To retrieve a representation of the running datastore in XML format, a client can send:

(Note the use of the 'verbose' query parameter, see Section 21.2.10, “Query Parameters”)

GET /api/running?verbose
Application:vnd.yang.api+xml

HTTP/1.1 200 OK
Server: 
Date: Wed, 12 Aug 2015 11:38:23 GMT
Last-Modified: Wed, 12 Aug 2015 11:38:23 GMT
Cache-Control: private, no-cache, must-revalidate, proxy-revalidate
Etag: 1439-379503-31029
Content-Type: application/vnd.yang.datastore+xml
Transfer-Encoding: chunked
Pragma: no-cache

<data xmlns:y="http://tail-f.com/ns/rest" y:self="/api/running">
  <sys xmlns="http://example.com/router" y:self="/api/running/sys">
 ...
  </sys>
 ...
  <operations>
    <lock y:self="/api/running/_lock">/api/running/_lock</lock>
    <rollback 
y:self="/api/running/_rollback">/api/running/_rollback</rollback>
  </operations>
</data>

            
    POST /api/running/_copy-running-to-startup
    Host: example.com
    Accept: application/vnd.yang.operations+xml
            

Note that any action defined as "config false" will only show up under the /api/operational datastore.

    ...
    <blaha xmlns="http://example.com/ns/ktm"
           y:self="/api/operational/blaha">
      <y:operations y:path="/blaha">
        <bar y:self="/api/operational/blaha/_operations/bar"/>
        <!-- NOTE: this action is defined as 'config false'
             and hence, shows up under the 'operational'
             datastore  -->
      </y:operations>
    </blaha>
    ...
          

In order to list available a rollback files, a client can send:

GET /api/rollbacks
Application:vnd.yang.api+xml

<rollbacks xmlns="http://tail-f.com/ns/rest" 
xmlns:y="http://tail-f.com/ns/rest">
  <file>
    <name>0</name>
    <creator>admin</creator>
    <date>2015-08-12 13:38:23</date>
    <via>rest</via>
    <label></label>
    <comment></comment>
  </file>
  <file>
    <name>1</name>
    <creator>admin</creator>
    <date>2015-08-12 13:38:22</date>
    <via>rest</via>
    <label></label>
    <comment></comment>
  </file>
</rollbacks>

Note how each rollback file is represented as separate resources, e.g. "/api/rollbacks/0". We can also see how the 'rollback-label' and 'rollback-comment' is used in "/api/rollbacks/0/label" and "/api/rollbacks/0/comment". These resources can be inspected individually and a client can send:

GET /api/rollbacks/0
Application:vnd.yang.api+xml

# Created by: admin
# Date: 2015-08-12 13:38:23
# Via: rest
# Type: delta
# Label: 
# Comment: 
# No: 10016

sys {
    interfaces {
        serial ppp0 {
            ppp {
                accounting acme;
            }
            authentication {
                method    eap;
                list-name foobar;
            }
            authorization admin;
            multilink {
                group 1;
            }
        }
    }
 }

The payload is in the same curly bracket rollback format as used in the NETCONF, CLI and Web UI agents.

To apply a rollback file to a database use the appropriate "rollback" resource/operation in the datastore of your choice:

GET /api/running
Application:vnd.yang.datastore+xml

<data xmlns:y="http://tail-f.com/ns/rest">
  <sys xmlns="http://example.com/router">
 ...
  </sys>
 ...
  <operations>
    <lock>/api/running/_lock</lock>
    <rollback>/api/running/_rollback</rollback>
  </operations>
</data>

POST /api/running/_rollback
Content-Type: application/vnd.yang.data+xml
<file>0</file>

HTTP/1.1 204