Common API Characteristics (REST, NETCONF, RESTCONF)

The Need for a Common Language

Before we discuss the APIs themselves, we must address a foundational concept: structured versus unstructured data. As a network professional, your primary interface to a device has likely been the Command-Line Interface (CLI). While human-readable, CLI output is unstructured text. For a script or program, parsing this text is brittle and unreliable; a minor change in a software update (like adding a column to a show command) can break your automation.

Modern network automation requires structured data. This is data formatted in a predictable, hierarchical way that is easy for machines to parse and validate. This is where a data modeling language comes into play.

In modern networking, that language is YANG (Yet Another Next Generation). Think of YANG as a standardized way to create a "schema" or blueprint for a network device's configuration and operational data. It defines what data exists (e.g., an interface, a BGP neighbor), its type (e.g., string, integer), and how it's organized.

To get a better feel for what YANG is and why it's important, let's watch a short explanation from Hank Preston, a well-known voice in the network automation community.

With YANG providing the common data models, NETCONF and RESTCONF act as the transport protocols to access and manipulate that data.

API Characteristics: REST, NETCONF, and RESTCONF

Now, let's explore the three key APIs mentioned in the learning outcome. We will look at their underlying transport, data encoding, and operational models.

1. REST APIs (A Quick Review in Context)

As you know, REST (Representational State Transfer) is not a protocol but an architectural style. When we talk about a "REST API," we generally mean an API that adheres to REST principles and uses HTTP/S for transport.

In the networking world, you'll encounter two main flavors of REST APIs:

• Native REST APIs: These are vendor-specific APIs. A good example is Cisco's NX-API REST for the Nexus platform. While it's a RESTful API using HTTP/S and returning JSON/XML, the structure of the API calls (the URIs) and the data models it uses are specific to that platform (it uses the Management Information Tree or MIT, not YANG directly).
• Standards-based RESTful APIs: This is where RESTCONF fits in, which we will detail shortly.

Your existing knowledge of HTTP methods (GET, POST, PUT, DELETE), status codes, and JSON/XML is directly applicable here. The key difference in the networking context is what the "resource" is—instead of a user profile on a website, it's a router interface, a BGP configuration, or a table of ARP entries.

2. NETCONF (Network Configuration Protocol)

NETCONF is a robust, IETF-standard protocol (RFC 6241) built from the ground up specifically for installing, manipulating, and deleting the configuration of network devices. It was designed to overcome the limitations of older methods like SNMP and CLI scraping.

Let's watch a brief overview of the NETCONF model.

Based on the video and its specification, here are the key characteristics of NETCONF:

• Transport: Uses SSH as its transport protocol, typically on port 830. This makes it familiar and secure from a network administrator's perspective.
• Encoding: Strictly uses XML (Extensible Markup Language) for all messages.
• Operations: It has a well-defined set of RPC-style operations. The most common are:
  • <get-config>: Retrieve all or part of a specified configuration datastore.
  • <edit-config>: Modify a configuration datastore.
  • <get>: Retrieve running configuration and device state information.
  • <copy-config>: Copy an entire configuration datastore to another.
  • <delete-config>: Delete a configuration datastore.
• Key Feature - Datastores: NETCONF formally defines the concept of separate configuration datastores, such as running, candidate, and startup. This allows you to make changes to a candidate configuration, validate them, and then commit them to the running configuration as a single transaction.
• Key Feature - Transactions: NETCONF supports atomic transactions. When you commit a set of changes, either all of them succeed, or none of them do. The system automatically rolls back if an error occurs. This is a massive advantage for reliability over executing CLI commands one by one.

3. RESTCONF

While NETCONF is powerful, its reliance on XML and a specific RPC model can be a barrier for web and application developers who are more accustomed to RESTful interfaces. RESTCONF (RFC 8040) was created to bridge this gap. It provides a REST-like API to access the same YANG-defined data that NETCONF uses.

Key characteristics of RESTCONF:

• Transport: Uses HTTPS, typically on port 443. This makes it firewall-friendly and easy to use with common programming libraries.
• Encoding: Supports both XML and JSON, giving the client flexibility to choose their preferred format using HTTP Accept headers.
• Operations: It maps standard HTTP methods to operations on the YANG data models. For example:
  • GET: Corresponds to retrieving data (<get>).
  • POST: Used to create resources.
  • PUT: Used to replace resources.
  • PATCH: Used to modify a resource.
  • DELETE: Used to delete a resource.
• Key Feature - Accessibility: By using standard HTTP/S and supporting JSON, RESTCONF makes network programmability accessible to a much broader range of developers.

It's crucial to understand that RESTCONF is not just any REST API. It is a standard that defines how HTTP methods and URIs are mapped specifically to YANG models.

Head-to-Head Comparison

To consolidate these concepts, let's turn to a very useful comparison table from a Cisco Live presentation. This document provides a side-by-side analysis that is perfect for both deep understanding and exam review.

Here is a summary of the key trade-offs from that resource:

Conclusion

In this lesson, we've dissected the characteristics of the three main types of APIs you'll encounter in network automation. We have moved from the general principles of REST to the network-specific, standardized protocols of NETCONF and RESTCONF.

Key Takeaways:

• Modern network automation is built on structured data, with YANG serving as the standard modeling language.
• REST APIs in networking can be native (vendor-specific) or standards-based.
• NETCONF is a powerful, RPC-based protocol over SSH using XML. Its main strengths are its robust transactional capabilities and support for multiple configuration datastores.
• RESTCONF provides a RESTful interface to YANG models over HTTPS, supporting both JSON and XML. It lowers the barrier to entry for developers and integrates easily with web-based tools.
• The choice between NETCONF and RESTCONF depends on the use case: NETCONF for reliability and complex configuration changes, RESTCONF for accessibility and simple data retrieval/modification.

Preview of the Next Lesson:
Now that we understand the APIs that transport the data, our next lesson will focus on the data itself. The learning outcome will be to "interpret JSON encoded data returned from a REST API call." Since you're already familiar with the format, we will focus on practical examples from network devices, understanding how to navigate the nested structures to extract the specific information you need for your automation scripts.