Describe characteristics of REST-based APIs

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:
 Fig
ure 1. Postman – Disable SSL Certificate Verification

Read with HTTP GET

In the first example, we will send a simple GET request to obtain a list of interfaces of the router.

Figure 2. REST
API READ
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

Fig
ure 3. Postman –GET Request Parameters
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.
 Fig
ure 4. Postman – Read list of the Router’s 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.
 Fig
ure 5. Postman – Read list of the Router’s Interfaces in JSON Format

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).

Fig
ure 6. Cisco IOS-XE REST API Create an Interface with HTTP POST
Figure 7 shows Postman configuration for this request.

Fig
ure 7. Postman – Create an Interface with HTTP POST
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.

Fig
ure 8. REST API Update with HTTP PATCH
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.
 Fig
ure 9. Postman – Updating Interface Description using HTTP PATCH
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.
 Figur
e 8. REST API Delete with HTTP DELETE
Figure 9 shows configuration parameters in Postman.

Fig
ure 9. Postman – Deleting Interface with HTTP DELETE
And the listing below demonstrates that the interface doesn’t exist anymore:

Router#show run interface Loopback1

^
% Invalid input detected at '^' marker.

Recommended Books (Amazon links):

CCNA 200-301 Official Cert Guide Library by Wendell Odom
Cisco CCNA Certification, 2 Volume Set: Exam 200-301 by Todd Lammle
Programming and Automating Cisco Networks: A guide to network programmability and automation
in the data center, campus, and WAN (Networking Technology) by Ryan Tischer
Transforming Campus Networks to Intent-Based Networking by Pieter-Jan Nefkens

Self-Test Questions
What is REST and RESTful API?
REpresentational State Transfer (REST) is an architectural style that defines a set of constraints to
create APIs. RESTful API is an API that meets all the constraints.

Does RESTful API have to be HTTP-based?

No, REST doesn’t mandate the use of any specific protocols.

What is the difference between Resource and Representation in REST?

A resource is a named piece of information, while a representation of the resource is a description of
the resource at a specific moment.

Map CRUD operations to HTTP verbs

Create – POST or PUT.
Read – GET.
Update – PATCH or PUT (by replace).
Delete – DELETE