# Cisco IOS XE REST API and NETCONF

> Chapter 8 of the Courseiva CISCO-DEVNET-ASSOCIATE curriculum — https://courseiva.com/learn/cisco-devnet-associate/cisco-ios-xe-rest-api

**Official objective:** 5.1 — Describe Cisco IOS XE REST API and NETCONF/YANG for device management

## Introduction

Exam objective 5.1 for the Cisco DevNet Associate 200-901 focuses on device management using modern, programmable interfaces. Understanding how to talk to network devices using APIs instead of typing commands is a fundamental shift in how IT professionals now manage networks. This chapter explains what the Cisco IOS XE REST API and NETCONF/YANG are, why they replace traditional methods, and what you need to know for the exam.

## The Restaurant Ordering System Analogy

Have you ever ordered a pizza from a busy restaurant? You call the restaurant, a person answers, you tell them what you want, they write it down, go to the kitchen, come back, and say 'it'll be 20 minutes.' That works, but it's slow. You can't see the menu while you're on the phone. If you want to change your order, you have to call again and hope the same person answers. The restaurant can't easily tell you 'we're out of pepperoni' until you ask.

Now, what if the restaurant had a website? You log in, you see the full menu (including what's in stock), you pick your toppings, you submit the order, and instantly you get a confirmation. You can check the order status any time. You can add a side dish without calling anyone. The restaurant's computer system talks directly to your screen, not through a person. That is the difference between the old way of managing network devices (command-line interface, or CLI) and the new way using APIs like REST and NETCONF. The restaurant's ordering website is the REST API. The list of ingredients and preparation steps the kitchen uses is the YANG model. And the digital system that lets the website and the kitchen talk is NETCONF.

## Core explanation

To understand the Cisco IOS XE REST API and NETCONF/YANG, first you must understand the problem they solve. Traditionally, to configure a Cisco router or switch (a network device), you would open a terminal program, log in, and type specific commands one at a time. This is called the Command-Line Interface (CLI). It is like building a car by telling an engineer every single step: 'Turn this bolt. Now turn that bolt. Now check the oil.' It works, but it is slow, error-prone, and difficult to automate.

Imagine you manage 500 devices. Using CLI, you would have to log into each one, type the same commands 500 times, and pray you did not make a typo on the 499th device. This is not scalable. This is where Programmable Interfaces come in. They allow you to manage many devices using software, scripts, or tools. The two main approaches for Cisco devices are the REST API and NETCONF/YANG.

Let's start with REST API. REST stands for Representational State Transfer. It is a style of designing web services. When you visit a website, your browser uses HTTP (Hypertext Transfer Protocol) — that's the 'language' of the web. A REST API lets you send HTTP requests to a server (like a router) to read or change its configuration. The Cisco IOS XE REST API is a specific version of this that runs on Cisco's operating system (IOS XE). You send commands like GET (to read data), POST (to create new data), PUT (to update data), and DELETE (to remove data). The server responds in a structured format called JSON (JavaScript Object Notation) or XML (eXtensible Markup Language). JSON looks like this: {"hostname": "Router1", "interface": "GigabitEthernet0/0"}. It is easy for computers and humans to read.

Now, what about NETCONF and YANG? NETCONF stands for Network Configuration Protocol. It is a standard protocol (a set of rules) for installing, manipulating, and deleting the configuration of network devices. Think of it as a specialised delivery truck for network configurations. YANG stands for Yet Another Next Generation. It is a data modelling language — it describes the structure of the data. If NETCONF is the truck, YANG is the map that tells the truck exactly where to go and what to pick up. YANG defines what configurations are valid on a device. For example, a YANG model for an interface says: 'an interface has a name, an IP address, and a status that can be 'up' or 'down'.' This is a strict, precise definition.

The key difference from REST API is that NETCONF is designed specifically for network devices. It uses Remote Procedure Calls (RPCs) — basically, 'calls' to the device that say 'do this operation.' It operates over SSH (Secure Shell) or TLS (Transport Layer Security) for security. NETCONF also has a feature called 'datastores' — separate, predictable places to store different types of configuration data. The three main datastores are:

- candidate: a working copy of the configuration you are editing; changes are not active until you commit them
- running: the configuration that is currently active on the device
- startup: the configuration that loads when the device boots up

Why does this matter? Because when you use CLI, you change the running config directly, and if you make a mistake, the device might break immediately. With NETCONF, you edit the candidate config, validate it, and then commit it. If the validation fails, the device stays untouched.

Cisco IOS XE supports both REST API and NETCONF/YANG. The REST API is simpler for basic tasks like reading data or making quick changes. NETCONF/YANG is more powerful for complex, automated configuration management, especially when you manage hundreds of devices. The 200-901 exam tests your understanding of these concepts, not deep programming. You need to know what each technology is for and when you would choose one over the other.

## Real-world context

An IT professional managing a network for a mid-sized company (say, 300 employees across three offices) receives a request from the security team: 'We need to update the ACL (Access Control List) on every router to block a new malicious IP address.' ACLs are rules that allow or block traffic. In the past, this person would open a terminal, connect to each router via SSH, type 'config t', then paste the ACL commands, then type 'exit', then save the configuration. For three routers, that is tedious. For twenty routers, it is a whole morning's work with high risk of human error.

Using a programmable approach, the IT professional writes a simple Python script that uses the Cisco IOS XE REST API. The script does the following:

- Connects to the device using HTTPS (secure HTTP) and authenticates with credentials or an API token
- Sends a GET request to fetch the current ACL configuration to confirm the existing rules
- Sends a PUT request with a JSON payload containing the new ACL entry to block the IP address
- Sends a GET request to verify the change was applied successfully
- Logs the result for audit purposes

The whole process for ten routers takes less than two minutes. The script can be reused any time the security team makes a request. If the team uses a network management tool like Ansible (automation tool) or Python with the ncclient library (for NETCONF), they could also use NETCONF. They would define the desired ACL configuration using a YANG model. They would connect to each device via NETCONF, push the candidate configuration, validate it, and commit it. The result is the same — the change is made — but NETCONF gives stronger guarantees that the change is syntactically correct before it is applied.

Another common real-world task is collecting inventory data. A network manager needs to know the model, serial number, and software version of every device. Using CLI, they would log into each device and type 'show version'. Using the REST API, they send a single GET request to the device's '/api/v1/device/info' endpoint and receive a JSON response with all that data. They can then write a script that loops through all device IP addresses and aggregates the data into a spreadsheet or a dashboard.

In the exam, you will not be asked to write a script. But you will be asked to interpret what such a script does. For example, if you see a script that sends a PUT request to an API endpoint with a JSON payload, you should know that it is updating a resource, not reading it. The real-world takeaway is that these technologies let you treat your network as a programmable system, not a collection of boxes that need manual typing.

## Exam focus

The 200-901 exam tests objective 5.1 'Describe Cisco IOS XE REST API and NETCONF/YANG for device management' in several specific ways. You will not be asked to write code, but you will be asked to understand concepts, compare technologies, and interpret basic outputs.

Firstly, the exam loves to test the difference between REST API and NETCONF. They will present a scenario and ask which technology is better suited. The traps are subtle. For example:

- A question might say 'You need to make a quick, stateless query to check the CPU utilisation of a router.' The correct answer is REST API, because it is simpler and designed for read operations, while NETCONF is transactional and more suited for configuration changes.
- Another question: 'You need to make a multi-step configuration change where all changes must apply together or not at all.' The correct answer is NETCONF, because of its candidate datastore and commit operations.

The exam tests you on the HTTP methods used with REST API:

- GET: read data
- POST: create new data
- PUT: update/replace existing data
- PATCH: partially update data (less common in IOS XE, but know it exists)
- DELETE: remove data

They will present a question like: 'Which HTTP method should be used to add a new interface to a router?' The answer is POST. If they ask 'Which method should be used to change the IP address of an existing interface?' The answer is PUT.

For NETCONF, the exam focuses on these specific terms:

- RPC (Remote Procedure Call): the operation type, such as <get>, <get-config>, <edit-config>, <commit>
- Datastores: candidate, running, startup
- YANG as the data model — it defines what is configurable
- The fact that NETCONF uses XML for its messages
- Operations are performed over SSH (default port 830) or TLS

The exam also tests the concept of 'idempotency'. A PUT request is idempotent — sending it ten times has the same effect as sending it once. A POST request is not idempotent — sending it ten times creates ten resources. This is a classic trap.

Another common trap involves the 'commit' operation. With CLI, changes are immediate. With NETCONF, changes hit the candidate datastore first. If you forget to commit, the changes are not applied. The exam will present a scenario where a candidate configuration is edited but not committed, and ask what the device's current state is. The correct answer: the running configuration is unchanged.

Finally, the exam tests your understanding of the triple: REST API, NETCONF, and YANG. Know that REST API uses HTTP verbs and returns JSON or XML. NETCONF uses RPCs and XML, and relies on YANG models. YANG is not a protocol — it is a language for defining data structures. A YANG model is like a blueprint. The actual data transmitted uses XML encoding.

## Step by step

1. **1. Identify the Management Need** — Decide what you need to do: read a piece of data (like CPU usage), change a configuration (like adding an interface), or delete a configuration. This determines whether you use GET (read), POST/PUT (write), or DELETE.
2. **2. Choose the Interface: REST API or NETCONF** — For simple, one-off reads or quick changes, choose REST API (HTTP-based). For transactional, multi-step configuration changes that must apply together or roll back, choose NETCONF (which uses candidate datastores and commit operations).
3. **3. Authenticate and Establish a Connection** — For REST API, you connect over HTTPS (port 443) and provide credentials (username/password or an API token) in the request header. For NETCONF, you connect over SSH (port 830) using SSH keys or passwords.
4. **4. Build and Send the Request** — If using REST API, you choose the correct HTTP method (e.g., GET) and URL endpoint (e.g., /api/v1/interface). You include a JSON payload if needed (POST/PUT). If using NETCONF, you build an XML message containing the appropriate RPC (e.g., <get-config> or <edit-config>) and send it.
5. **5. Handle the Response and Validate** — The device sends back a response. For REST API, this is a JSON/XML payload with a status code (200 OK, 201 Created, 204 No Content, 400 Bad Request, 500 Internal Server Error). For NETCONF, the response is an XML message with an <ok> tag or error information. Always verify the change was applied correctly.
6. **6. Commit (if using NETCONF) or Save (if using CLI)** — With NETCONF, changes go to the candidate datastore and must be explicitly committed to become active. With REST API, changes are typically applied immediately to the running configuration. For persistence across reboots, you may need to save the running config to startup explicitly, although the REST API can handle that too.

## Comparisons

### REST API vs NETCONF

**REST API:**
- Uses HTTP methods (GET, POST, PUT, DELETE)
- Returns data in JSON (most common) or XML
- Simple, stateless, good for quick reads and writes

**NETCONF:**
- Uses Remote Procedure Calls (RPCs) over SSH or TLS
- Always uses XML for encoding messages
- Transactional with candidate/commit; better for complex config changes

### YANG vs NETCONF

**YANG:**
- Data modelling language; defines structure and constraints
- Not a protocol — does not transmit data
- Describes what data is valid (e.g., interface must have a name, IP, status)

**NETCONF:**
- Network management protocol; transports data
- Defines operations like <get>, <edit-config>, <commit>
- Uses YANG models to understand the structure of the data it handles

### GET Request vs POST Request

**GET Request:**
- Used to read data from a resource
- Idempotent — making the same GET request multiple times returns the same data
- Does not change the state of the device

**POST Request:**
- Used to create a new resource
- Not idempotent — sending the same POST multiple times creates multiple resources
- Changes the state of the device (adds new configuration)

### PUT Request vs PATCH Request

**PUT Request:**
- Used to replace an entire resource with new data
- Idempotent — sending the same PUT twice has the same effect as once
- If you omit a field with PUT, that field is reset to default or removed

**PATCH Request:**
- Used for partial updates — only modifies the fields you specify
- Not always idempotent depending on implementation
- Other fields in the resource remain unchanged

### CLI (Command-Line Interface) vs REST API

**CLI (Command-Line Interface):**
- Human-oriented, requires typing commands manually
- Changes are immediate and can break the device if mistyped
- Hard to automate at scale (requires screen scraping or expect scripts)

**REST API:**
- Machine-oriented, uses structured data (JSON/XML)
- Changes can be validated before applying (depending on endpoint)
- Easy to automate with scripts; can manage hundreds of devices from one script

## Diagram

_Flowchart showing the two primary ways to manage a Cisco IOS XE device: via REST API (HTTP) or via NETCONF (XML RPC), both validated by YANG models._

```mermaid
graph LR
    A[Network Admin or Script] --> B{REST API or NETCONF?}
    B -->|REST API| C[HTTP Request: GET/POST/PUT/DELETE]
    B -->|NETCONF| D[XML RPC: get-config/edit-config/commit]
    C --> E[Cisco IOS XE Device]
    D --> E
    E --> F[Response: JSON or XML with status/data]
    E --> G[YANG Model defines valid structure]
    G -.-> D
    G -.-> C
```

## Common misconceptions

- **Misconception:** REST API and NETCONF are the same thing; you can use them interchangeably for any task. **Reality:** They are different technologies. REST API is a web service interface using HTTP. NETCONF is a network management protocol with specific operations like commit. They serve different purposes — REST is simpler for read-heavy tasks, NETCONF is better for transactional configuration. (Both involve sending requests to a device and getting responses, so beginners assume they are just different brands of the same thing. The exam relies on you knowing the functional differences.)
- **Misconception:** YANG is a protocol that sends data between devices. **Reality:** YANG is a data modelling language, not a protocol. It defines the structure and constraints of configuration data. The data is then transmitted using protocols like NETCONF or RESTCONF. Think of YANG as the grammar rules; NETCONF is the conversation. (The acronym 'YANG' and the fact that it is always used with 'NETCONF' makes people think it is a communication protocol. It is a modelling language.)
- **Misconception:** Cisco IOS XE REST API can only handle GET requests. **Reality:** It supports standard HTTP methods: GET, POST, PUT, PATCH, DELETE. It is a full CRUD (Create, Read, Update, Delete) interface. (Many beginners see the REST API as a 'read-only' reporting tool because the exam focuses on GET for monitoring. Cisco IOS XE REST API is fully programmable for configuration changes.)
- **Misconception:** NETCONF and CLI are essentially the same because both involve typing commands into a terminal. **Reality:** NETCONF is a structured, automated protocol that uses well-defined data models and operations. CLI is a human-oriented, unstructured interface. NETCONF is designed for machines to talk to devices; CLI is designed for humans to type. (Both can be used to achieve the same end result (configure a device), so novices think they are just different speeds of the same tool. The key is automation versus manual input.)
- **Misconception:** You cannot use NETCONF with a REST API — they are mutually exclusive. **Reality:** Cisco IOS XE devices can support both simultaneously. You can use REST API for some tasks and NETCONF for others, depending on the requirement. (The exam presents them as separate answers, leading students to think a device can only support one. In reality, modern devices have multiple management interfaces available at the same time.)

## Key takeaways

- REST API uses standard HTTP methods (GET, POST, PUT, DELETE) over HTTPS to read and write configuration on Cisco IOS XE devices.
- NETCONF is a network management protocol that uses Remote Procedure Calls (RPCs) and relies on YANG data models to define configuration structure.
- YANG is a data modelling language, not a protocol; it defines what configuration items are valid and what their constraints are.
- NETCONF has a candidate datastore that allows you to stage configuration changes and commit them atomically, reducing the risk of breaking a live network.
- The main HTTP methods tested are GET (read), POST (create), PUT (update/replace), and DELETE (delete), with idempotency being a key distinguishing feature between PUT (idempotent) and POST (not idempotent).
- The 200-901 exam focuses on conceptual understanding: you must know when to choose REST API versus NETCONF, and be able to interpret basic API requests and NETCONF operations.
- Cisco IOS XE supports both REST API and NETCONF simultaneously, giving you flexibility in how you manage devices.

## FAQ

**What is the difference between REST API and NETCONF?**

REST API is a web-based interface that uses standard HTTP methods (GET, POST, etc.) and returns data in JSON or XML format. NETCONF is a specialised network management protocol that uses RPCs and XML, and has features like candidate datastores and transactional commit. REST is simpler for reads; NETCONF is more powerful for complex configuration changes.

**Is YANG the same as NETCONF?**

No. YANG is a data modelling language that defines the structure of configuration and state data. NETCONF is the protocol that transports that data. You use a YANG model to describe what can be configured, and NETCONF to read or write that configuration.

**Can I use REST API to configure a router from a web browser?**

Indirectly, yes. You can type the URL (like http://router-ip/api/v1/interface) in a browser to send a GET request and see the data. But for POST/PUT/DELETE, you need a tool like Postman, cURL, or a script. Most browsers only send GET requests by default.

**What is the default port for NETCONF?**

The default port for NETCONF over SSH is 830. Some implementations may use port 22 (the standard SSH port), but the standard is 830.

**Do I need to know Python to pass the 200-901 exam?**

Not deeply. The exam focuses on concepts. You may be asked to read a simple Python script that calls an API or uses NETCONF, but you won't be asked to write one from scratch. You do need to understand the meaning of HTTP methods and basic data structures like JSON and XML.

**What is the 'candidate' datastore in NETCONF?**

The candidate datastore is a working copy of the configuration. You can make changes to it without affecting the running configuration. When you are ready, you use the <commit> operation to apply those changes to the running configuration. This prevents partial or broken changes from taking effect immediately.

## Check your understanding

1. **Which NETCONF datastore holds the configuration that will be loaded when the device boots up?**

   Answer: The startup datastore.

2. **If you want to change the IP address of an existing interface on a router using the Cisco IOS XE REST API, which HTTP method should you use?**

   Answer: You should use PUT, because you are replacing the existing interface resource with new data.

3. **What is the primary purpose of YANG in the context of NETCONF?**

   Answer: YANG is a data modelling language that defines the structure, constraints, and validation rules for configuration and state data exchanged via NETCONF.

4. **What does the NETCONF <commit> operation do?**

   Answer: It moves the configuration changes from the candidate datastore to the running datastore, making them active on the device.

5. **True or False: a REST API POST request is idempotent.**

   Answer: False. POST requests are not idempotent; sending the same POST request multiple times will create multiple resources.

---

Interactive version with quiz and diagrams: https://courseiva.com/learn/cisco-devnet-associate/cisco-ios-xe-rest-api