APIs have the potential to simplify the work of network administrators. They make it possible to perform the same type of functionality as commands entered in the CLI but also more functionality and in a much larger context than a simple LAN.
CLI commands are not designed to support cloud-scale network equipment, or those of smart devices (or “smart devices”: any more or less programmable, independent device) potentially residing on a remote site. In these use cases, configurations based on CLI commands often lead to tedious tasks and human error.
APIs are also the primary gateway to programmable networks, which automate configuration and telemetry procedures. For example, a single API request is sufficient to deploy a software update to a thousand network devices, while it will be necessary to proceed device by device using the API.
The same goes for reconfiguring ports or load balancing rules, whether on physical equipment, or logical networks that span many physical installations. For telemetry of several networked devices, the API allows results to be filtered in the first stages to monitor only relevant information.
Principle
In the field of networking, the SSH (Secure Shell) protocol is traditionally used to access remote equipment in a secure manner. As part of using APIs to manage network equipment, the HTTP or HTTPS protocols are used to send requests to the APIs.
HTTP and HTTPS protocols are usually used with a web browser. To communicate with APIs without managing the network, we use the cURL command line or Postman graphical interface.
In principle, it involves interacting with the API by sending commands, on the device’s extended URL, that will be used to create, read, write, or clear parameters, which are often in JSON format.
JSON format is used as a standard for data exchange; It is supported by many programming languages and tools. JSON is human-readable and machine-parsable. Administrators use the information in JSON format to embed it into the API or use it in network automation.
In the context of network equipment, there are typically three standard APIs, used by most manufacturers: RestConf and NetConf which are used to configure and monitor devices, as well as OpenFlow which is used to redefine topology (routing, load balancing, identification of connected equipment, etc.) . For example, the RestConf API’s extended URL on a machine whose IP address is usually 172.31.0.1 https://172.31.0.1/restconf/.
In terms of possible interactions, the HTTP and HTTPS protocols provide commands (also called “verbs” or “methods”) which each correspond to a type of action. Knowing that these actions here will be used to create, read, write, or erase information in the context of a conversation with APIs, we can remember their meaning by drawing a parallel to the set of CRUD commands that we use to create, read, write, or erase information when interacting with databases via an API Applications.
| HTTP did | rough work |
|
|
Creates |
|
Gets |
is reading |
|
Put |
to update |
|
patch |
to update |
|
wipe up |
wipe up |
The cURL command line tool is used to send data to and from the server. This tool is widely used due to its rich functionality, such as support for multiple protocols, especially HTTP and HTTPS.
Postman is a GUI based API testing platform with over 20 million users worldwide. It helps developers to design, build, test and improve their APIs by multiplying iterations. Using the tool simplifies the API workflow in test and production environments.
At this point, the administrator has the means to interact with the network equipment’s APIs. Interactions relate to obtaining or processing data. In the networking field, data is basically a configuration of the equipment.
Examples of interactions with cURL
In this first example, we are connecting to a router whose IP address is 172.31.0.1. We achieve this over HTTPS with the following command:
curl -k https://172.31.0.1/restconf/ -u "cisco:cisco"
Here, ‘-k’ is used to communicate ignoring the SSL certificate and ‘-u’ is used to state the username (“cisco”), and then the password (“cisco” too).
This command will produce the following display, where we see that the parameters of this router are definable in the YANG language.
The next step is to collect information about the network interface of that router to which we are connected. This information includes the primary IP address, description, and forwarding parameters. This information is useful to administrators when analyzing and troubleshooting networks.
To inspect an interface on a Cisco device, administrators typically use the following Cisco IOS command:
'show interface <interface name>'
In HTTP/HTTPS we just have to specify the set of data we want to read in the URL. This dataset in this case is that of the interface gigabit ethernet countable 1 It is part of the original interfaces that can be referenced from the database cisco-IOS-XE-
local from the router.
Without anything else, the interface-related information will be displayed in XML, ie as a string of values corresponding to the parameters displayed on both sides with “
It’s good practice to dump custom XML and use JSON instead, which provides greater security, as evidenced by the ranking of the most common flaws on the web according toI agree.
To retrieve this result in JSON format, we add a header to our request that we specify with “-H”. This header will be interpreted by the RestConf API as a command. In this case, the “Accept:” command that tells YANG to output content in JSON format.
curl -H "Accept: application/yang-data+json" -k
https://172.31.0.1/restconf/data/cisco-IOS-XE-
native:native/interface/gigabitethernet=1 -u "cisco":"cisco"
This query will result in the data being displayed in JSON format:
In the previous two examples, we did not use the HTTP/HTTPS method on the command line. The GET method is implicit. Now here’s an example where we’ll turn off the interface. This involves changing the only “off” parameter in the interface dataset.
In HTTP/HTTPS it is a matter of sending a PATCH request. To tell cURL that PATCH is the HTTP/HTTPS method here, we prefix it with “-X”. To specify a new “True” value to place on the “off” parameter of interface “1” between the original Cisco-IOS-XE dataset: GigabitEthernet dataset”, we prefix the entire path with “-d”:
$ curl -X PATCH -H "Content-Type: application/yang-data+json" -H
"Accept: application/yang/data+json" -d '{Cisco-IOS-XE-native:
GigabitEthernet": [{"name": "1", "shutdown": true}]}' -k
https://172.31.0.1/restconf/data/Cisco-IOS-XE-
native:native/interface/GigabitEthernet=1 -u "cisco":"cisco"
Examples of interaction with the postman
Postman is often easier to use than cURL. To get information about the native interface of our router, we just have to choose the GET method and specify the URL as before:
Gets – https://172.31.0.1/restconf/data/Cisco-IOS-XE-native:native/interface
Go to the “Authorization” and “Headers” tabs in Postman to fill in the access parameters. Go to “Body” to read the result in JSON format.
To save new parameters to an interface, simply change them in ‘Body’ and then use the POST method with the same URL
The POST method rewrites the entire dataset of the interface. If you prefer to use the debug method to change only one parameter without affecting the others, you will therefore have to specify the path to that parameter in the URL.
Postman’s unique feature is the ability to run Python code, which can be easier to write when it comes to automating interactions with the API.
