15.3 RESTCONF Protocol Operations: HTTP Verbs, Datastores, and Response Codes

RESTCONF Protocol Operations: HTTP Verbs, Datastores, and Response Codes

As enterprise networks shifted toward programmatic infrastructure management, the Internet Engineering Task Force (IETF) standardized NETCONF (Network Configuration Protocol, RFC 6241) and YANG (Yet Another Next Generation data modeling language, RFC 6020 / RFC 7950) to replace unstructured CLI screen-scraping and SNMP. While NETCONF successfully established a robust, transaction-safe, model-driven foundation, its reliance on XML-only encoding and stateful SSH transport sessions over TCP port 830 created integration challenges for cloud-native applications, web developers, and lightweight automation scripts that standardly operate over web protocols. To bridge this gap, the IETF developed RESTCONF (RFC 8040), defining an HTTP-based, stateless protocol that provides programmatic access to YANG-modeled network configuration and operational state.

+-------------------------------------------------------------------------+
|               Model-Driven Interface Protocol Comparison                |
+-------------------------------------------------------------------------+
|                                                                         |
|   +-----------------------------------------------------------------+   |
|   |                   YANG Data Models (Schema Contract)            |   |
|   |   - Cisco Native Models (Cisco-IOS-XE-native.yang)              |   |
|   |   - OpenConfig Models (openconfig-interfaces.yang)              |   |
|   |   - IETF Models (ietf-interfaces.yang - RFC 8343)               |   |
|   +-----------------------------------------------------------------+   |
|                 |                                   |                   |
|                 v                                   v                   |
|   +---------------------------+       +-----------------------------+   |
|   |     NETCONF (RFC 6241)    |       |     RESTCONF (RFC 8040)     |   |
|   | - Transport: SSH (TCP 830)|       | - Transport: HTTPS (TCP 443)|   |
|   | - Encoding: Strictly XML  |       | - Encoding: JSON or XML     |   |
|   | - Protocol: Stateful RPCs |       | - Protocol: Stateless REST  |   |
|   | - Operations: <get-config>|       | - Operations: GET, POST,    |   |
|   |   <edit-config>, <commit> |       |   PUT, PATCH, DELETE        |   |
|   +---------------------------+       +-----------------------------+   |
|                 |                                   |                   |
|                 +-----------------+-----------------+                   |
|                                   |                                     |
|                                   v                                     |
|   +-----------------------------------------------------------------+   |
|   |       Cisco IOS XE Device Datastores (Unified Data Store)       |   |
|   |   Running Datastore  |  Candidate Datastore  |  Operational State|  |
|   +-----------------------------------------------------------------+   |
+-------------------------------------------------------------------------+

Protocol Architecture: RESTCONF vs. NETCONF

RESTCONF does not replace NETCONF; rather, it provides a RESTful alternative interface accessing the exact same underlying YANG data models and system datastores. Understanding their architectural differences is vital when designing automation pipelines:

• Transport Mechanism: NETCONF uses a persistent, stateful SSH subsystem running on TCP port 830 (RFC 6242), requiring ongoing connection maintenance and capability exchanges (<hello>). RESTCONF uses stateless HTTPS connections over standard TCP port 443 (or HTTP on port 80 in lab environments), easily traversing corporate firewalls and application proxies.
• Data Serialization: NETCONF strictly mandates XML-encoded payloads. RESTCONF natively supports both JSON and XML. Because JSON produces substantially smaller payloads and maps directly to native dictionaries and lists in Python, JavaScript, and Go, it is the preferred serialization format in modern automation.
• Media Types and Headers: RESTCONF defines distinct MIME media types for content negotiation:
  • For JSON: application/yang-data+json
  • For XML: application/yang-data+xml Automation clients use the Content-Type request header to specify the format of the data being sent to the router, and the Accept header to declare the format expected in the response.

NETCONF vs. RESTCONF Architectural Comparison

Root Resource Discovery and URI Anatomy

RESTCONF organizes all network data hierarchically into a conceptual datastore addressable via Uniform Resource Identifiers (URIs).

+-------------------------------------------------------------------------+
|                    RESTCONF URI Structural Anatomy                      |
+-------------------------------------------------------------------------+

  https://10.1.1.1/restconf/data/ietf-interfaces:interfaces/interface=GigabitEthernet1
  \______________/\_______/\___/\_________________________/\_________________________/
         |            |      |               |                           |
      Scheme &     Root    Resource        YANG Module &             List Entry &
     Host/Port     Path      Type         Top-Level Container         Unique Key

1. Root Resource Discovery (/.well-known/host-meta)

RFC 8040 mandates discovery of the RESTCONF API root resource via the standard Web Host Metadata mechanism (RFC 6415). A client initiates discovery by querying:

GET /.well-known/host-meta HTTP/1.1
Host: router.example.com
Accept: application/xrd+xml

The network device responds with an Extensible Resource Descriptor (XRD) document containing a link relation pointing to the RESTCONF entry point, typically /restconf:

<XRD xmlns='http://docs.oasis-open.org/ns/xri/xrd-1.0'>
  <Link rel='restconf' href='/restconf'/>
</XRD>

2. Top-Level Entry Points under /restconf

Under the /restconf root URI, the device provides three standard resource entry points:

• /restconf/data: The primary operational resource. Represents the unified configuration and operational datastore for all loaded YANG models.
• /restconf/operations: The entry point for executing YANG-modeled Remote Procedure Calls (such as triggering an operating system reload, clearing interface counters, or restarting a routing process).
• /restconf/yang-library-version: Reports the version of the IETF YANG Library specification implemented by the device (e.g., "2019-01-04"). The full catalog of supported YANG modules, revisions, and feature sets can be queried at /restconf/data/ietf-yang-library:yang-library.

3. URI Path Parameters and Query Options

To target specific data subtrees, URIs follow the YANG schema path:

• module-name:container: The top container must be prefixed with the YANG module identifier to avoid naming collisions (e.g., ietf-interfaces:interfaces vs Cisco-IOS-XE-native:native).
• list=key: Lists are indexed by specifying the key leaf after an equals sign (e.g., interface=GigabitEthernet1 or neighbor=10.1.1.2).

Clients append query parameters to control output scope:

• ?content=config: Returns only configuration data (config true nodes). Matches NETCONF <get-config>.
• ?content=nonconfig: Returns only operational state data (config false nodes, such as hardware counters). Matches operational filtering in NETCONF <get>.
• ?content=all: Returns both configuration and operational state data (default behavior).
• ?depth=N: Limits the nesting depth of returned JSON/XML trees to N levels, preventing massive payload downloads on large modular switches.
• ?fields=leaf1;leaf2: Selectively filters the response to include only specific attributes.

Mapping HTTP Verbs to Datastore Operations

RESTCONF maps standard HTTP methods deterministically to YANG datastore transactions and NETCONF equivalents:

+-------------------------------------------------------------------------+
|               HTTP Verbs to Datastore Operations Mapping                |
+-------------------------------------------------------------------------+
                                                                           
  HTTP Verb     Target Resource URI             Datastore Operation        
  ---------     -------------------             -------------------        
  GET           /data/.../interface=Gi1         Retrieve configuration/state
                                                (NETCONF: <get>, <get-config>)
                                                                           
  POST          /data/.../interfaces            Create new child list entry
                /operations/cisco-ia:save-config Invoke YANG RPC           
                                                                           
  PUT           /data/.../interface=Loopback1   Create or REPLACE resource 
                                                (Overwrites entire entity) 
                                                                           
  PATCH         /data/.../interface=Gi1         MERGE partial modification 
                                                (Leaves siblings intact)   
                                                                           
  DELETE        /data/.../interface=Loopback1   Remove target resource     
                                                (NETCONF: operation="delete")

Detailed HTTP Method Semantics

1. GET (Retrieve Data)

Retrieves configuration and/or operational state from the target resource. Does not modify the datastore. Depending on the ?content parameter, GET functions as a NETCONF <get-config> or <get>.

2. POST (Create Child or Execute RPC)

Serves two distinct functions in RESTCONF:

• Resource Creation: When targeted at a parent data container or list resource, POST creates a new child resource. Crucially, the resource must not already exist. If the resource already exists in the datastore, the server rejects the request with an HTTP 409 Conflict error.
• RPC Invocation: When targeted at a resource under /restconf/operations, POST executes a defined RPC action (such as saving running-config to startup-config).

3. PUT (Create or Replace Target Resource)

Creates or completely replaces the target resource at the exact URI specified. Unlike POST (which targets the parent), PUT targets the exact resource URI. If the resource does not exist, it is created. If it already exists, the entire resource is overwritten. Any configuration leaves omitted from the request body are either deleted or reset to their schema defaults.

4. PATCH (Merge / Partial Modification)

Applies partial modifications to the target resource without replacing omitted sibling elements. PATCH corresponds directly to NETCONF's default <edit-config> behavior with operation="merge". If an engineer wants to update an interface description without altering its IP address, MTU, or administrative shutdown state, PATCH is the appropriate method. RFC 8072 also defines YANG Patch, an advanced mechanism for executing atomic multi-operation patches.

5. DELETE (Remove Resource)

Deletes the target data resource from the datastore. Corresponds to NETCONF <edit-config> with operation="delete". If the targeted resource does not exist, the request fails with an error instead of silently succeeding.

HTTP Verbs to NETCONF RPC Mapping Reference

HTTP Response Status Codes in RESTCONF

RESTCONF servers return standardized HTTP status codes to communicate transaction outcomes:

Success Codes (2xx)

• 200 OK: The request succeeded and the response has a body. Returned for successful GET requests and for a PATCH that returns data.
• 201 Created: A new data resource was created, either by POST or by a PUT that targeted a resource that did not yet exist. The response includes a Location header containing the absolute URI of the newly created resource.
• 204 No Content: The request succeeded, but the server returns no message body. Standard for successful DELETE operations, as well as PUT or PATCH updates where no body is returned.

Client Error Codes (4xx)

• 400 Bad Request: The request payload violates syntax rules, contains invalid JSON/XML formatting, or breaches YANG schema constraints (e.g., providing a VLAN ID of 5000 when the schema restricts values to 1–4094).
• 401 Unauthorized: The request lacked authentication credentials or provided invalid credentials (e.g., bad HTTP Basic Auth username/password).
• 403 Forbidden: The authenticated user has insufficient permissions to perform the requested operation (e.g., AAA privilege level or RBAC restrictions).
• 404 Not Found: The requested URI path does not exist in the YANG datastore.
• 409 Conflict: A conflict occurred. Triggered when a POST request attempts to create a resource that already exists, or when a datastore lock contention prevents an edit.

Server Error Codes (5xx)

• 500 Internal Server Error: The router operating system or RESTCONF subsystem encountered an unrecoverable internal error or crash while processing the transaction.

RESTCONF HTTP Response Status Codes Reference

Practical Python RESTCONF Script Walkthrough

The following Python script interacts with a Cisco IOS XE router via RESTCONF. It demonstrates querying interface configuration and operational counters (GET), modifying the interface description without affecting existing parameters (PATCH), and verifying status codes:

import json
import requests
from requests.auth import HTTPBasicAuth
import urllib3

# Suppress TLS certificate warnings for lab environments
urllib3.disable_warnings(urllib3.exceptions.InsecureRequestWarning)

ROUTER_IP = "10.1.1.1"
USERNAME = "cisco"
PASSWORD = "cisco123!"
BASE_URL = f"https://{ROUTER_IP}/restconf"

# Define standard RESTCONF media types
RESTCONF_HEADERS = {
    "Accept": "application/yang-data+json",
    "Content-Type": "application/yang-data+json"
}


def get_interface_state(interface_name):
    """Retrieves configuration and operational state using GET with ?content=all."""
    url = f"{BASE_URL}/data/ietf-interfaces:interfaces/interface={interface_name}"
    params = {"content": "all"}
    
    response = requests.get(
        url,
        headers=RESTCONF_HEADERS,
        auth=HTTPBasicAuth(USERNAME, PASSWORD),
        params=params,
        verify=False,
        timeout=10
    )
    
    if response.status_code == 200:
        data = response.json()
        intf = data.get("ietf-interfaces:interface", {})
        print(f"Interface: {intf.get('name')}")
        print(f"  Description: {intf.get('description', 'None configured')}")
        print(f"  Admin Enabled: {intf.get('enabled')}")
        print(f"  Operational Status: {intf.get('oper-status')}")
        return data
    elif response.status_code == 404:
        print(f"Interface {interface_name} not found on device (HTTP 404).")
        return None
    else:
        print(f"Error retrieving interface: HTTP {response.status_code}")
        response.raise_for_status()


def update_interface_description(interface_name, new_description):
    """Merges a new description using PATCH without overwriting existing settings."""
    url = f"{BASE_URL}/data/ietf-interfaces:interfaces/interface={interface_name}"
    
    payload = {
        "ietf-interfaces:interface": {
            "name": interface_name,
            "description": new_description
        }
    }
    
    response = requests.patch(
        url,
        headers=RESTCONF_HEADERS,
        auth=HTTPBasicAuth(USERNAME, PASSWORD),
        json=payload,
        verify=False,
        timeout=10
    )
    
    # Successful PATCH operations typically return 200 OK or 204 No Content
    if response.status_code in [200, 204]:
        print(f"Successfully updated description on {interface_name} (HTTP {response.status_code}).")
    elif response.status_code == 400:
        print("HTTP 400 Bad Request: Check payload structure and YANG schema constraints.")
    elif response.status_code == 409:
        print("HTTP 409 Conflict: Datastore is currently locked or conflicting edit.")
    else:
        print(f"Failed to update interface: HTTP {response.status_code}")
        print(response.text)


if __name__ == "__main__":
    target_intf = "GigabitEthernet1"
    
    print("--- 1. Querying Interface State Before Update ---")
    get_interface_state(target_intf)
    
    print("\n--- 2. Applying Partial Update via PATCH ---")
    new_desc = "Uplink-to-Core-Switch-01 [Updated-via-RESTCONF]"
    update_interface_description(target_intf, new_desc)
    
    print("\n--- 3. Verifying Updated State ---")
    get_interface_state(target_intf)