In this blog post, we will discuss REST-based APIs. We will also demonstrate how to use such APIs with step-by-step scenarios using a Cisco virtual router running on the ESXi platform.
This article aims to help CCNA candidates in preparing for the following exam topic:
6.5 Describe characteristics of REST-based APIs (CRUD, HTTP verbs, and data encoding)
APIs and Representational State Transfer (REST)
Application Programming Interface (API)
API of an application or a service specifies how other applications can access and change its information. For example, a service may expect certain parameters to be specified when a client application makes a request. The service generates some output as a response, which is also part of API.
A network device manufacture develops and maintains API. CCNA candidates should understand how to use APIs from the client perspective. Automation scripts and software use APIs that network devices expose.
Command-Line Interface (CLI) cannot be classified as API. It provides means to change how a device operates, but its primary purpose is to interact with a user, i.e. not with another program. CLI, however, can be used in automation scripts, which interactively send and parse command output.
SNMP operation fits the definition of API. However, it didn’t receive wide adoption in network automation and is mostly used in read-only monitoring.
Cisco devices and controllers expose RESTful APIs, i.e. APIs that meet specific architectural criteria. We will discuss this type of API in the following section.
RESTful API
REST defines a set of architectural guidelines that were defined by Roy Fielding in his dissertation.
REST is not a protocol and doesn’t provide specific implementation details. For example, it doesn’t mandate the use of HTTP, which is, however, is most often used and often associated with REST APIs.
REST defines a set of constraints that must be met for a web service to be considered RESTful. The full list of constraints is:
- Must have client-server architecture.
- RESTful services must have a uniform interface.
- The client must track the state of the session and send request containing all information required to process such a request. The server must not store user session context information.
- The server must state whether information can be cached on the client.
- The system must have a hierarchical layered design.
- The server can send executable code to a client to extend its functionality.
RESTful API constraints provide multiple benefits for an application and are important for an API designer to follow. However, for a network engineer, the main areas of focus are centered around how to access and change information behind API.
REST Resources and Representation
In REST API a resource is any type of information that can have a name. For example, a network interface or an access list can be used as resources in API.
A resource is identified with a Uniform Resource Identifier (URI). Type of URI that specifies a location and access protocol of a resource is called Unified Resource Locator (URL). When a client sends a request to REST API, it must include a resource identifier. For example, if HTTP is used as protocol, the URL of https://fastreroute.com/category/ccna consists of the URI scheme of HTTPS, followed by colon, authority “//”, hostname – fastreroute.com, and resource identifier (or path) – /category/ccna.
Representation of a resource is a self-describing state of a resource at a specific moment. The server provides a representation of a resource to the client, which can perform different operations on the resource. For example, the representation of the resource identified with the URL in the previous paragraph is an HTML page that contains all CCNA posts of the blog. REST APIs can return representation as a serialized object, for example, in (JavaScript Object Notation) JSON format.
CRUD and HTTP Verbs
CRUD stands for 4 generic types of operations that can be applied to data:
- Create
- Read
- Update
- Delete
HTTP request methods, also called verbs, can be mapped to CRUD operations. For example, in an HTTP-based RESTful API, a client can change the parameters of a network interface by using the HTTP PATCH method. We will show how it can be done in the example section.
HTTP GET method corresponds to Read operation. The server responds with a representation of a resource identified by URI.
HTTP POST verb Creates a child or subordinate to resource specified in URI.
HTTP PUT maps to both Update and Create operations. If a resource specified in the PUT request exists on the server, it should be replaced with the one in the request. If the resource doesn’t exist, PUT can create it.
HTTP PATCH verb can also perform the Update operation. PATCH contains instructions on how to update a resource, while PUT contains a modified copy of a resource.
HTTP DELETE maps to Delete operation.
REST API Example: CSR1000v
Let’s apply concepts from the previous section to practice. The next few sections will show how to perform each of CRUD operations with REST-like API provided by Cisco IOS-XE routers.
This API is based on RESTCONF. It can return the representation of resources in XML or JSON formats. RESTCONF uses YANG, which is modeling language describing a router’s configuration and operation states.
Both RESTCONF and YANG are described in RFCs:
- 8040 RESTCONF Protocol (https://tools.ietf.org/html/rfc8040)
- 6020 YANG – A Data Modeling Language for the Network Configuration Protocol NETCONF (https://tools.ietf.org/html/rfc6020)
IOS-XE Configuration for RESTCONF
In our example, we will generate API requests to a CSR1000v IOS-XE router running on ESXi.
Our router runs IOS-XE version 16.9.5 with the following configuration applied:
interface GigabitEthernet1 ip address 192.168.7.4 255.255.255.0 no shutdown aaa new-model aaa authentication login default local aaa authorization exec default local username admin secret ciscocisco username admin privilege 15 enable secret ciscocisco ip http server ip http authentication local ip http secure-server restconf
Refer for details to the Cisco configuration guide, which is available via this URL.
Postman Client Setup
We will use free tier features of software called Postman (https://www.postman.com/).
Postman helps with testing and discovery of API prior to writing automation programs. The automation scripts can be written using programming languages, such as Python with requests library.
Download the software for the platform of your choice. We use the Windows version of Postman in the next examples and the screenshots.
Start Postman and disable SSL certificate validation, as we are going to use the router’s IP address and self-signed certificate in our examples:
Read with HTTP GET
In the first example, we will send a simple GET request to obtain a list of interfaces of the router.
The next figure shows the sequence of steps creating the request in Postman that returns the list of interfaces of the router. The username and password values must match ones configured on the router.
In this example, the URL of https://192.168.7.4/restconf/data/Cisco-IOS-XE-native:native/interface/ consists of the following components:
- https – URI scheme and protocol
- // – authority
- 192.168.7.4 – hostname or IP address of the router
- /restconf/data/Cisco-IOS-XE-native:native/interface/ – path or resource ID
The result of the request is shown in the next screenshot. The server replied back with a 200 OK message and a representation of its interfaces in XML format.
To switch to JSON we can adjust the request by modifying Headers as shown in Figure 5. Accept key is set to value of application/yang-data+json. The response looks very similar to the one in Figure 4, as both XML and JSON represent the same resource – a list of interfaces of the router.
Create new interface with HTTP POST
As the next step, let’s create a new loopback interface using the HTTP POST verb. Figure 6 demonstrates a message exchange between the client using URI representing a list of interfaces and the POST method containing the JSON representation of the new loopback interface. The server returns HTTP response with the code of 201 (created).
Figure 7 shows Postman configuration for this request.
The listing below shows JSON representation of the interface:
{
"Cisco-IOS-XE-native:Loopback": {
"name": "1",
"description": "Test",
"ip": {
"address": {
"primary": {
"address": "192.168.8.1",
"mask": "255.255.255.255"
}
}
}
}
}
The router has its configuration updated with new Loopback1 interface:
ROUTER#show run interface Loopback1 ! interface Loopback1 description Test ip address 192.168.8.1 255.255.255.255 !
Update interface description with HTTP PATCH
In this example, we will create a query that sets the GigabitEthernet1 interface’s description. Figure 8 shows the message exchange between the PC and the router. URI includes interface name, as PATCH is used to apply partial updates to an existing interface.
Postman query configuration steps are shown in Figure 9. Note that authorization settings must be set in the same way as done in the HTTP GET example.
The listing below shows JSON representation of the description change:
{
"Cisco-IOS-XE-native:GigabitEthernet": {
"description": "Very Important Interface",
}
}
The router has its configuration updated with a description:
ROUTER#show run interface GigabitEthernet1 ! interface GigabitEthernet1 description Very Important Interface ip address 192.168.7.4 255.255.255.0 negotiation auto no mop enabled no mop sysid !
Delete interface description with HTTP DELETE
The final example will delete the Loopback interface using the HTTP DELETE verb. Figure 8 shows the message exchange, which identifies the resource that we want to delete.
Figure 9 shows configuration parameters in Postman.
And the listing below demonstrates that the interface doesn’t exist anymore:
Router#show run interface Loopback1
^
% Invalid input detected at '^' marker.