REST API

A REST API (Representational State Transfer Application Programming Interface) is a set of rules that allows systems to communicate using the HTTP protocol, the same protocol your browser uses to access websites.

Imagine managing hundreds of network devices without typing a single CLI command. That’s the power of REST APIs. They allow software to communicate directly with your network devices to automate repetitive configuration and monitoring tasks.

Why REST APIs Matter in Networking

In traditional networking, engineers connect manually to each device to configure them one by one. With REST APIs, a single request can apply changes, collect data, or perform actions across multiple devices simultaneously.

Figure 1 - Manual CLI vs REST API automation across multiple devices.

This fundamental difference is what enables network automation, using software or controllers to push configurations, gather information, and maintain consistency efficiently across the entire network.

In network automation, REST APIs are often used to exchange information between automation tools and network devices.

This communication typically involves three components: REST API Client (like your automation script), a REST API Server, and a Network Device.

Each of them plays a distinct role in sending, processing, and responding to requests.

Understanding the Client–Server Model

The REST API follows a client–server model where each side has a clear responsibility.

• The client sends an HTTP request to perform an action, such as retrieving, creating, updating, or deleting data.
  

• The server interprets the request, interacts with the interested device, and then returns a response to the client.

Figure 2 – REST API Client–Server Communication Model

As shown in Figure 3, the REST API client sends an HTTP GET request to the API server, which forwards it to the network device.

Once the device responds, the server sends the data back to the client in a structured format such as JSON.

In simple terms, the client sends a request, the API server processes it, and the device returns a response with the required data. This model is at the heart of network automation, allowing consistent and scalable communication between systems.

REST APIs use HTTP methods to describe the type of action you want to perform.
These actions follow the CRUD model, which stands for:

• Create – add new data

• Read – retrieve existing data

• Update – modify existing data

• Delete – remove data

Each CRUD action corresponds to a specific HTTP method used in network automation.

Table 1 - CRUD Methods Overview

Each method works like a verb in a sentence.
It defines what kind of action you’re asking the API to perform.

For example:

• A GET request retrieves information, such as interface status or device inventory.

• A POST request creates a new resource, like adding VLAN 20 to a switch.

• A PUT request updates an existing configuration, for instance changing all interface settings.

• A PATCH request modifies a specific field, such as updating only an interface description.

• A DELETE request removes an existing resource, like deleting VLAN 10 from the device.

These simple verbs form the foundation of REST API communication.
Once you understand them, you can interpret any REST request and know exactly what it is designed to do.

Once you’ve defined what action you want to perform, you also need to specify where you want to act.
That’s the purpose of the URI (Uniform Resource Identifier).

A URI identifies the exact resource that the REST API should interact with.
In network automation, this could represent a device, an interface, a VLAN, or any other configurable element.

Understanding the Structure of a REST URI

Every REST API request includes a URI that tells the system where to act.
Think of it as the “address” of the resource you want to reach.

For example, if you use Cisco DNA Center’s API to retrieve network device information, the URI may look like this:

Figure 3 – Breakdown of a REST API URI

Figure 3 below visually breaks down each part of this URI so you can clearly see how it’s built and what role each segment plays.

Each element in this figure has a specific function:

• Method (GET) → Defines what you’re doing — in this case, retrieving information.
  

• Protocol + Host (https://sandboxdnac.cisco.com) → Tells the client where to send the request, using HTTPS for secure communication.
  

• Resource Path (/dna/intent/api/v1/network-device) → Specifies what part of the API you want to interact with — here, the list of network devices.

Together, they form a clear and structured address that allows your automation script to target the exact resource it needs.

Adding Query Parameters

Sometimes, you don’t want all devices or data, you need to filter your request.
That’s where query parameters come in. They let you specify conditions such as a particular IP address or hostname.

For example:

Figure 4 – REST API URI with Query Parameters

This request asks Cisco DNA Center to return information only about the device with the management IP 10.10.20.175.

Here’s what happens conceptually:

• Your automation tool sends a GET request to the Cisco DNA Center server.
  

• The server interprets the URI and checks for a match in its database.
  

• Since a query parameter is included, it only returns information about the matching device.

Each part of a URI helps the API locate the right data, just like a postal address.
When you master how to read and construct URIs, you gain precise control over your network automation workflows.

REST isn’t a protocol. It’s an architectural style that defines how systems communicate in a simple, scalable, and reliable way.
Understanding these principles helps you see why REST APIs are the foundation of modern network automation.

Core Principles of REST

Table 2 – REST Architectural Principles Overview

Why It Matters

These principles are what make REST APIs reliable and adaptable.
They allow tools like Ansible, Postman, and Cisco DNA Center to communicate efficiently, scale easily, and stay flexible across different network environments.

When you send an API call, you’re not just asking for data. You’re interacting with a resource inside a system designed for automation, consistency, and long-term scalability.

After sending a REST API request, the server replies with a status code that indicates whether the operation succeeded or failed. These codes are part of every API response and help you understand how your automation task was processed.

Table 5 – Common HTTP Status Codes

When working with APIs, you’ll quickly notice that some codes appear very often.
For example, 200 OK means your request worked perfectly, your script got the response it expected.
But sometimes, things don’t go as planned.

Let’s take a concrete example.

The 404 “Not Found” Error

You’ve probably seen a 404 page while browsing the web that says “The requested URL was not found on this server.”

Figure 5 - HTTP Status Code 404

It’s the same principle with REST APIs.
When your script sends a GET request for a device that doesn’t exist or a wrong URI, the network controller replies with 404 Not Found to tell you:

“I received your request, but there’s no resource matching this address.”

• REST APIs allow automation tools to communicate directly with network devices using the HTTP protocol.

• CRUD operations define what you want to do — Create, Read, Update, or Delete a resource.

• URIs specify where you want to act by identifying the exact resource or device.

• REST principles make network automation scalable, reliable, and consistent.

• HTTP status codes help you confirm whether a request succeeded or failed during automation.

Mastering these fundamentals gives you a solid foundation for network automation.
In the next lesson, you’ll explore REST API authentication, learning how to securely interact with APIs and access protected resources.