11.3 RESTCONF API Operations & Cisco Catalyst Center Intent APIs

11.3 RESTCONF API Operations & Cisco Catalyst Center Intent APIs

Core Blueprint Focus: Domain 7.0 (Automation and AI) evaluates candidate expertise across two levels of programmability: direct device-level interaction via RESTCONF and centralized controller orchestration via Cisco Catalyst Center. While NETCONF is ideal for stateful, transactional automation over SSH, web developers and cloud orchestration pipelines favor a RESTful, HTTP-native interface consuming JSON payloads. RFC 8040 defines RESTCONF to provide this capability on the Cisco Catalyst 9800 WLC. At the enterprise orchestration layer, Cisco Catalyst Center exposes Intent-Based Networking APIs for campus-wide wireless lifecycle management.

---

1. RESTCONF Protocol Fundamentals (RFC 8040)

RESTCONF is an IETF standard protocol (RFC 8040) that provides an HTTP-based interface for applications to access and manipulate configuration and operational data defined in YANG data models. It adopts the architectural principles of Representational State Transfer (REST) while enforcing the rigorous schema validation of YANG.

Architectural Comparison: RESTCONF vs. NETCONF

---

2. RESTCONF Architecture & URI Structure

RESTCONF maps YANG schema hierarchies directly into predictable Uniform Resource Identifier (URI) paths:

https://<wlc-ip>:<port>/restconf/<root-resource>/<yang-module>:<container>/<list>=<key>

Standard Root Resources

Under the top-level /restconf/ path, the protocol exposes three standardized root entry points:

• /restconf/data/: Access point for all configuration and operational state data modeled in YANG. To query or configure a resource, append the YANG container path to this URI.
• /restconf/operations/: Access point for invoking Remote Procedure Calls (RPCs) defined within YANG modules (e.g., triggering an AP reboot or manual channel reset).
• /restconf/yang-library-version: Returns the version of the IETF YANG library implemented by the wireless controller.

HTTP Method Mapping to Wireless Datastore Operations

RESTCONF maps standard HTTP verbs to network datastore modifications:

• GET (Read Resource): Retrieves configuration data or live operational telemetry from /restconf/data/. Equivalent to NETCONF <get> or <get-config>. Returns 200 OK.
• POST (Create Resource or Invoke RPC): Creates a child data node within a parent list or container. Also used under /restconf/operations/ to execute an RPC command. If successful, returns 201 Created with a Location header indicating the URI of the new resource.
• PUT (Replace or Create): Creates or completely replaces the target resource at the specified URI. If the resource exists, it is overwritten entirely; if it does not exist, it is created. Returns 200 OK or 201 Created.
• PATCH (Partial Update / Merge): Modifies specific attributes of an existing resource without altering other properties. Equivalent to NETCONF <edit-config> with default-operation='merge'. Returns 200 OK or 204 No Content.
• DELETE (Remove Resource): Deletes the target resource identified by the URI. Equivalent to NETCONF <edit-config> with operation='delete'. Returns 204 No Content.

Query Parameters for Telemetry Filtering

RESTCONF supports standardized URL query parameters to refine queries:

• ?content=config: Retrieves configuration data only (ignoring operational telemetry).
• ?content=nonconfig: Retrieves operational state telemetry only.
• ?depth=N: Limits the depth of nested child containers returned (e.g., ?depth=1 returns top-level container leaves only).
• ?fields=leaf1;leaf2: Returns only the specified attributes, reducing network bandwidth.

---

3. Cisco Catalyst Center Intent APIs

While RESTCONF manages individual wireless controllers, Cisco Catalyst Center provides centralized intent-based network management. Its northbound Intent APIs allow network engineers to manage policies, provision campus sites, automate device onboarding, and monitor client assurance across hundreds of WLCs and thousands of Access Points.

Northbound Intent API Architecture

Catalyst Center organizes its APIs into functional architectural domains:

1. Authentication: Manages session tokens via /dna/system/api/v1/auth/token.
2. Site Design & Hierarchy: Defines geographic areas, buildings, and floors (/dna/intent/api/v1/site) and manages wireless network profiles (/dna/intent/api/v1/wireless/profile).
3. Device Onboarding (Plug and Play): Automates initial device claiming and Day-0 configuration push (/dna/intent/api/v1/onboarding/pnp-device).
4. Assurance & Telemetry: Exposes health scores (1–10), client connection latency, and RF telemetry (/dna/intent/api/v1/client-health, /dna/intent/api/v1/network-device).

Token Authentication Workflow

Catalyst Center enforces a token-based authentication lifecycle for all northbound API requests:

1. Authentication Request: The client sends an HTTP POST request to https://<catalyst-center-fqdn>/dna/system/api/v1/auth/token.
2. Credentials: The request includes HTTP Basic Authentication in the Authorization header containing the Base64-encoded username and password (Authorization: Basic <base64-string>).
3. Token Issuance: Catalyst Center verifies credentials and returns a JSON payload containing a Token string (valid for 1 hour by default):

   {
     "Token": "eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ9..."
   }
   

4. Subsequent API Invocations: For all subsequent requests, the client omits the Basic Auth header and instead passes the token in a custom header: X-Auth-Token: <token>.

Core Wireless Intent API Endpoints

---

4. Secure Python Automation: Catalyst Center Token & Client Health Query

Use an authenticated session, retrieve secrets from an approved external source, verify TLS with the enterprise CA, set timeouts, check status codes, and keep the token out of logs.

import os
import requests
from requests.auth import HTTPBasicAuth

BASE = os.environ['CATALYST_CENTER_URL'].rstrip('/')
CA_BUNDLE = os.environ['NETWORK_CA_BUNDLE']
USER = os.environ['CATALYST_CENTER_USERNAME']
PASSWORD = os.environ['CATALYST_CENTER_PASSWORD']

with requests.Session() as session:
    session.verify = CA_BUNDLE

    auth_reply = session.post(
        f'{BASE}/dna/system/api/v1/auth/token',
        auth=HTTPBasicAuth(USER, PASSWORD),
        timeout=(5, 30),
    )
    auth_reply.raise_for_status()
    token = auth_reply.json()['Token']

    headers = {'X-Auth-Token': token, 'Accept': 'application/json'}
    devices_reply = session.get(
        f'{BASE}/dna/intent/api/v1/network-device',
        headers=headers,
        params={'family': 'Wireless Controller'},
        timeout=(5, 30),
    )
    devices_reply.raise_for_status()
    wireless_controllers = devices_reply.json().get('response', [])

    health_reply = session.get(
        f'{BASE}/dna/intent/api/v1/client-health',
        headers=headers,
        timeout=(5, 30),
    )
    health_reply.raise_for_status()
    client_health = health_reply.json().get('response', [])

A private enterprise CA is not a reason to disable verification; supply its CA bundle. Handle authentication, authorization, timeout, schema, and server failures separately in production, and avoid printing passwords or tokens.