Firefox https://cll-ng.cisco.

com/content/xtrac/1

Task 1: Use GET to Access Resources with a Browser

As with NETCONF, a very common use case for RESTCONF is getting portions of the running configuration datastore. With RESTCONF, you can get portions of the running configuration datastore with HTTP GET
requests, and see the result. The simplest way is to use a browser, like Firefox. Firefox on the Student Workstation can be configured to use edit to open XML results documents, so that you can easily view the results.

Step 1:
To begin, select the Firefox option from the left navigation bar on the Student Workstation.
Make the following selections:

Step 2:
Select the URL window, and enter the URL: http://csr1kv/restconf/api and press the Enter key.
Make the following selections:

Step 3:
On the pop-up Opening window, select OK (or press Enter) to open with the gedit application. The editor is opened.

Step 4:
In the editor window, the base RESTCONF GET URL is now displayed. Review the XML document. When you have finished viewing the document close the editor by selecting the "x" option at the upper left
of the browser window..
The XML document should be similar to the following example:
<api xmlns=”http://tail-f.com/ns/rest” xmlns:y=”http://tail-f.com/ns/rest”>
<version>0.5</version>
<config/>
<running/>
<operational/>
<operations>
<bd:clear-mac-address>/api/operations/bd:clear-mac-address</bd:clear-mac-address>
<bd:clear-bridge-domain>/api/operations/bd:clear-bridge-domain</bd:clear-bridge-domain>
<bd:create-parameterized-bridge-domains>/api/operations/bd:create-parameterized-bridge-domains</bd:create-parameterized-bridge-domains>
<cisco-ia:rollback>/api/operations/cisco-ia:rollback</cisco-ia:rollback>
<cisco-ia:save-config>/api/operations/cisco-ia:save-config</cisco-ia:save-config>
<cisco-ia:revert>/api/operations/cisco-ia:revert</cisco-ia:revert>
<cisco-ia:sync-from>/api/operations/cisco-ia:sync-from</cisco-ia:sync-from>
<cisco-ia:reset>/api/operations/cisco-ia:reset</cisco-ia:reset>
<cisco-ia:checkpoint>/api/operations/cisco-ia:checkpoint</cisco-ia:checkpoint>
<rt:fib-route>/api/operations/rt:fib-route</rt:fib-route>
</operations>
<rollbacks/>
</api>
This document, as the top-level resource in the API, shows the config, running, and operational datastores and the operations available at this level of the API. You can explore these resources by appending
them to the base URL.

1 din 7 27.05.2020, 09:57

Firefox https://cll-ng.cisco.com/content/xtrac/1

Step 5:
You are now viewing the original Firefox browser window. Select the URL window, and enter the URL: http://csr1kv/restconf/api/config/native and press the Enter key. The editor is opened.
Make the following selections:

Step 6:
In the editor window, Review the details of the http://csr1kv/restconf/api/config/native resource file. You may use the scroll up/down bar on the right portion of the page to review the entire file (also, you
can also use the Up/Down arrow to perform the same operation). When you are finished examining the XML file close the browser tab that you are viewing.
Make the following selections:

By now, you should recognize that this XML document structure is based on the ned.yang schema that you explored in the previous discovery labs with pyang and NETCONF.

So far, as you have explored resources, you may have noticed that you are not seeing everything that is defined in the YANG schema. By default, you see a subset of the available data with the resource
identifiers. The “deep” query parameter will show more.

Step 7:
Once again, select the URL window on the Firefox browser, and enter the URL: http://csr1kv/restconf/api/config/native/interface and press the Enter key. Review the file details. When you are finished
examining the XML file close the browser tab that you are viewing.
Make the following selections:

The following example shows you the results of this URL, where you see only the type and its identifier:
<interface …>
<GigabitEthernet>
<name>1</name>
</GigabitEthernet>
</interface>

Step 8:
Next, you will now use the deep query parameter to see more information. Once again, select the URL window on the Firefox browser, and enter the URL: http://csr1kv/restconf/api/config/native
/interface?deep and press the Enter key. Review the file details. When you are finished examining the XML file close the browser tab that you are viewing.
Make the following selections:

2 din 7 27.05.2020, 09:57

Firefox https://cll-ng.cisco.com/content/xtrac/1

The following example shows you results of the second URL, with the deep query parameter:
<interface …>
<GigabitEthernet>
<name>1</name>
<switch>
</switch>
<switchport>
<access>
</access>
<trunk>
<allowed>
<…output omitted…>

The difference between the last two examples is that the deep query parameter shows everything that could be configured, whereas without that query parameter, you see only the identifier. Next, you will
examine a specific instance of a resource.
As you step through the model hierarchy, you will need to address specific resources within containers. Each resource that is an instance of something that has a name that identifies that instance, for example,
GigabitEthernet interface 1.

Step 9:
Once again, select the URL window on the Firefox browser, and enter the URL: http://csr1kv/restconf/api/config/native/interface/GigabitEthernet/1 and press the Enter key. Review the file details. You
may use the scroll up/down bar on the right portion of the page to review the entire file (also, you can also use the Up/Down arrow to perform the same operation).
Make the following selections:

<GigabitEthernet …
<name>1</name>
<switch>
</switch>
<…output omitted…>
The name attribute is the “1” that is appended to this URL, so you are looking at the specific GigabitEthernet interface with “1” as the identifier. You can then start to look at specific parts of that resource
instance by appending additional path elements of the model schema to the URL.

Summary and Next Steps

In this task, you saw how easy it is to navigate the resources using RESTCONF GET requests. This process is almost exactly analogous to the <get> operation in NETCONF. Instead of creating filters, all you
need to do is add leaf names to the URL to drill into the data structure.
You can control the level of detail using the deep query parameter. A word of warning: in general, all that you will see that without the deep query parameter is the resource type and identifier. If you want to see
attributes that you have set on a resource, you need to add the deep query parameter. The deep query parameter allows you to see everything. You can also build a URL path specifically to the attributes you want
to see in a particular resource instance.
You can combine these simple techniques with what you learned about exploring the YANG schema with pyang, to construct URLs to access any part of the model.
You can also use these techniques with Postman. Note that RESTCONF uses basic authentication, that is, a username and password. You saw this process when you initially authenticated. With Postman, you
can also easily set the accept content-type header to JSON, which is less straightforward with a browser.
In the next tasks, you will see how to use RESTCONF with the Python requests library. Using Python allows you to change the content type for responses to JSON. You can also construct other request types to
update configuration, in the same way that you do with the ncclient.

Task 2: Use the Python Requests Library to Get Resources as XML and JSON

3 din 7 27.05.2020, 09:57

Firefox https://cll-ng.cisco.com/content/xtrac/1

The Python requests that the library is commonly used with RESTful interfaces like RESTCONF. In this task, you will see how to use the Python requests library to address the same use cases that you do in the
discovery lab “Use the ncclient Python Library” with ncclient and NETCONF.
You will use the xe_restconf_get_discovery_1.py sample code, which is located in the ~/git/code_files directory.

Step 1:
Select the File Explorer icon from the left navigation pane.
Make the following selection:

Step 2:
Double-click the git directory. Then, double-click the code_files directory. Finally, scroll down to locate the xe_restconf_get_discovery_1.py file to open it by double-clicking the icon for this file. The editor
is now displaying the contents of this file.
Make the following selections:

4 din 7 27.05.2020, 09:57

Firefox https://cll-ng.cisco.com/content/xtrac/1

Step 3:
Review the contents of the xe_restconf_get_discovery_1.py file and examine the code. You may use the scroll up/down bar on the right portion of the page to review the entire file (also, you can also use the
Up/Down arrow to perform the same operation). When you are finished examining the XML file close the browser tab that you are viewing.
Review the following code:
auth = HTTPBasicAuth('cisco', 'cisco')
url = 'http://csr1kv/restconf/api/config/native/interface'
response = requests.get(url, verify=False, auth=auth)

This code section gets the resource in the XML format, which is the default format. The main parts of the code are as follows:

The definition of auth is provided, using HTTP basic authentication. This definition is used in the requests.get(…) function call.
The definition of the url is provided, and is also used in the requests.get(…) function call.
The call to requests.get(…) function is shown.

The same code pattern gets the resources as JSON; the only difference is the inclusion of a header to define the accepted content type. To change the format of the response from XML to JSON, you simply include the
headers, as shown in the following relevant excerpts.
headers = { 'Accept': 'application/vnd.yang.data+json' }
response = requests.get(url, verify=False, headers=headers, auth=auth)
Including the headers as shown here is all that is required to change the format of the response from XML to JSON.
Adding the deep query parameter looks like the following:
response = requests.get(url+'?deep', verify=False, headers=headers, auth=auth)
To see the output, you can execute the code with the following commands:
$ cd ~/git/code_files
$ python xe_restconf_get_discovery_1.py

Task 3: Use the Python Requests Library with POST, PUT, and PATCH
As discussed previously, the differences between POST, PUT, and PATCH are important to understand. Usually, you do not want to POST or PUT resources when your intent is to update attributes of those resources.
For example, when updating an interface, a misused POST or PUT could result in overwriting interface attributes that are not defined in the message body. This situation could make the device unreachable, and
therefore unmanageable.
However, there could be circumstances in which this situation is exactly what you want. The device should have only the configuration that the management system defines and applies via RESTCONF. The correct
outcome is a product of your specific circumstances. The important issue is that you appreciate the differences.
You will use the sample code located in the ~/git/code_files directory.

Step 1:
Lets view how to use POST to create interface resources. Once again, select the File Explorer icon from the left navigation pane. Then, double-click the xe_restconf_post_discovery_1.py file to open it in the

5 din 7 27.05.2020, 09:57

Firefox https://cll-ng.cisco.com/content/xtrac/1

editor window. You may use the scroll up/down bar on the right portion of the page to review the entire file (also, you can also use the Up/Down arrow to perform the same operation).
Make the following selection:

Examine the xe_restconf_post_discovery_1.py sample code to understand how POST works.

The main parts of the code are shown here with explanations (elided for readability).
These variable declarations are the same as in the GET sample code in the previous task.
auth = HTTPBasicAuth('cisco', 'cisco')
url = 'http://csr1kv/restconf/api/config/native/interface'
xml_headers = {'Content-Type': 'application/vnd.yang.data+xml'}
The XML documents for creating interfaces are used in the POST calls.
gigabit_interface_data = """ <GigabitEthernet><name>1</name></GigabitEthernet>"""
loopback_interface_data = """<Loopback><name>1</name></Loopback>"""
The following attempt to POST the GigabitEthernet interface 1 will fail because the interface resource exists. POST will not overwrite existing resources.
requests.post(url, data=gigabit_interface_data, headers=xml_headers, verify=False, auth=auth)
This POST adds a new loopback interface.
requests.post(url, data=loopback_interface_data, headers=xml_headers, verify=False, auth=auth)
This DELETE will delete the loopback interface. Note that the path to the resource type, loopback, with the identifier, 1, appears as the last element in the URL and identifies the resource that will be deleted.
requests.delete(url+'/Loopback/1', verify=False, auth=auth)
To see the output, you can execute the code with the following command in the source code directory:
$ python ./xe_restconf_post_discovery_1.py

Step 2:
Next, you will view how to use PATCH and PUT to update interface resources. To begin, select the File Explorer icon from the left navigation pane. Then, double-click the
xe_restconf_patch_put_discovery_1.py file to open it in the editor window. You may use the scroll up/down bar on the right portion of the page to review the entire file (also, you can also use the Up/Down
arrow to perform the same operation).
Make the following selection:

Examine the xe_restconf_patch_put_discovery_1.py sample code to understand how PATCH and PUT work.
The main parts of the code are shown here with explanations (elided for readability). Many of the variables of the code are the same as in the previous step, so the focus in this step is on the logic.
These documents are XML documents that are used in the PUT and PATCH requests:
loopback _interface_data_min = """ <Loopback><name>1</name></Loopback>"""
loopback_interface_data_primary_address = """<Loopback><name>1</name><ip><address><primary><address>10.101.1.2
</address><mask>255.255.255.0</mask></primary></address></ip></Loopback>"""
loopback_interface_data_secondary_address = """<Loopback><name>1</name><ip><address><secondary><address>10.101.1.3
</address><mask>255.255.255.0</mask></secondary></address></ip></Loopback>"""
The following code uses PUT to create an interface in the same way as POST was used in the sample in the previous step, but with a URL that has the resource type and identifier appended.
requests.put(url+"/Loopback/1", data=loopback_interface_data_min,
headers=xml_headers, verify=False, auth=auth)
The following code uses PATCH to add a primary address. Note that the URL has the resource type appended.
requests.patch(url+"/Loopback", data=loopback_interface_data_primary_address,
headers=xml_headers, verify=False, auth=auth)
The following code attempts to use PUT to add a secondary address, that is, update the resource. This update fails because the semantics of PUT create a new resource and overwrite the attributes of an existing
resource. To create an interface, however, a primary address is required. The configuration subsystem rejects the configuration data because it does not contain a primary address.
response = requests.put(url+"/Loopback/1", data=loopback_interface_data_secondary_address, headers=xml_headers, verify=False, auth=auth)
The following code uses PATCH, which works because the semantics of PATCH update the attributes. This action is equivalent to the NETCONF <merge> operation= concept.
requests.patch(url+"/Loopback", data=loopback_interface_data_secondary_address,
headers=xml_headers, verify=False, auth=auth)

6 din 7 27.05.2020, 09:57

Firefox https://cll-ng.cisco.com/content/xtrac/1

To see the output, you can execute the code with the following command in the source code directory:
$ cd ~/git/code_files
$ python xe_restconf_patch_put_discovery_1.py

Step 3:
When you are finished examining the XML file, press the Enter key to end this lab.

7 din 7 27.05.2020, 09:57