Cisco Optical Network Controller TAPI Northbound Interface

Cisco Optical Network Controller acts as an optical domain controller, providing a T-API Northbound Interface (NBI) with RESTCONF and NETCONF support for exchanging TAPI model information with SDN-C clients like the Hierarchical Controller.

Enabling and Disabling the TAPI Northbound Interface

You can enable or disable the TAPI NBI. The TAPI NBI is disabled by default. Use the PUT /v2/tapi-state method as a user with admin privileges to enable or disable the TAPI NBI.

You must not enable TAPI NBI after Cisco Optical Network Controller onboards devices. Enable TAPI NBI before on-boarding any devices. To enable TAPI NBI after you have on-boarded devices, you must de-board all the devices and then enable TAPI NBI.

The following cURL command enables the TAPI NBI:

curl -L --request PUT \
--url 'https://{CONC-HOST}:8443/onc-devicemanager-service/v2/tapi-state?enableTapi=true' \
--user {username}:{password}

The following curl command disables the TAPI NBI:

curl -L --request PUT \
--url 'https://{CONC-HOST}:8443/onc-devicemanager-service/v2/tapi-state?enableTapi=false' \
--user {username}:{password}

TAPI Models

The TAPI specification builds on the Open Networking Foundation's (ONF) Core Information Model (CIM) and uses UML for its definition. The specification also uses UML to map to the YANG modeling language. Cisco Optical Network Controller NBI supports TAPI Version 2.1.3.

The following table lists the YANG models that compose the TAPI information model.

Table – List of TAPI YANG models

T-API is based on a context relationship between server and client. A Context is an abstraction that allows for logical isolation and grouping of network resource abstractions for specific purposes/applications and/or information exchange with its users/clients over an interface.

TAPI NBI Protocols & Operations

Cisco Optical Network Controller TAPI NBI supports the following protocols for facilitating communication between SDN-C client and Cisco Optical Network Controller TAPI NBI Server (SDN-C).

• RESTCONF
• NETCONF

TAPI is a model-driven interface. Hence it is possible to execute large number of Data API over RESTCONF/NETCONF interface. Cisco Optical Network Controller TAPI NBI supports retrieval of configuration/operational data as per the TAPI Models supported by it. It also supports provisioning operations on specific configuration data model, and notifications for any configuration/operational data changes happening within the SDN-C. The following table summarizes various NBI operations possible over Cisco Optical Network Controller TAPI NBI. All supported operations are available on both RESTCONF and NETCONF interfaces.

Table – TAPI NBI Operations Overview

Note: This document lists the retrieval operations that cover typical TAPI use cases. However, it is possible to execute other retrieval operations as per the various model paths supported within Cisco Optical Network Controller TAPI Model.

TAPI Context

T-API is based on a context relationship between a server and client. A Context is an abstraction that allows for logical isolation and grouping of network resource abstractions for specific purposes/applications and/or information exchange with its users/clients over an interface. The following table lists the TAPI Contexts and the support within Cisco Optical Network Controller TAPI NBI.

Table 2 – TAPI contexts and support within Cisco Optical Network Controller TAPI NBI

Note: Cisco Optical Network Controller TAPI NBI does not support notification-context and TAPI standard notifications. However, it supports NETCONF Event Notifications.

TAPI Network Layers

The TAPI models the network as a set of layers forming a client-server relationship. The TAPI layer-protocol-name indicates the technology layers that TAPI supports, while the layer-protocol-qualifier specifies the sub-layer within a specific technology. The following table indicates the network layers that are supported within TAPI and Cisco Optical Network Controller TAPI NBI.

Table – TAPI Network layers and support within Cisco Optical Network Controller TAPI NBI

TAPI Notifications

Overview

Cisco Optical Network Controller TAPI RESTCONF NBI supports YANG-defined event notifications. It preserves aspects of NETCONF event notifications while using the Server-Sent Events transport strategy. The system generates notifications whenever data changes, such as Create, Update, or Delete, occur within the TAPI database. Both Configuration and Operational data changes raise Notifications. Currently, Cisco Optical Network Controller TAPI NBI does not support Notification Replay feature.

Notification Subscription

TAPI client can subscribe for Notifications over the RESTCONF interface by using the following command: For JSON format:

curl --location --request GET 'https://{CONC-HOST}:8443/onc-nbi-service/restconf/streams/CONC_NETCONF/json' --user {username}:{password}

For XML format:

curl --location --request GET 'https://{CONC-HOST}:8443/onc-nbi-service/restconf/streams/CONC_NETCONF/xml' --user {username}:{password}

Create Notifications

The system generates a notification when the TAPI CDB creates an object. Notification Example:

{
  "ietf-restconf:notification": {
    "eventTime": "2021-05-19T14:59:49.4605+00:00",
    "ietf-netconf-notifications:netconf-config-change": {
      "changed-by": {
        "username": "admin",
        "session-id": 0,
        "source-host": "10.43.16.101"
      },
      "datastore": "running",
      "edit": [
        {
          "target": "/tapi-common:context/tapi-equipment:physical-context/tapi-equipment:device[tapi-equipment:uuid='306b36c5-bc9c-3b3f-ad01-94e834c270fd']/tapi-equipment:equipment[tapi-equipment:uuid='92e8b512-33e6-3e73-a795-ad903413bf76']",
          "operation": "create"
        }
      ]
    }
  }
}

Update Notifications

The system sends a notification when the TAPI CDB updates an object attribute. Notification Example:

{
  "ietf-restconf:notification": {
    "eventTime": "2021-05-19T15:00:56.238614+00:00",
    "ietf-netconf-notifications:netconf-config-change": {
      "changed-by": {
        "username": "admin",
        "session-id": 0,
        "source-host": "10.43.16.101"
      },
      "datastore": "running",
      "edit": [
        {
          "target": "/tapi-common:context/tapi-connectivity:connectivity-context/tapi-connectivity:connectivity-service[tapi-connectivity:uuid='ad818bed-25da-34b9-b98b-a8f0c56333b0']/tapi-connectivity:lifecycle-state",
          "operation": "replace"
        }
      ]
    }
  }
}

Delete Notifications

The system sends a notification when the TAPI CDB deletes an object. Notification Example:

{
  "ietf-restconf:notification": {
    "eventTime": "2021-05-19T15:00:56.68858+00:00",
    "ietf-netconf-notifications:netconf-config-change": {
      "changed-by": {
        "username": "admin",
        "session-id": 0,
        "source-host": "10.43.16.101"
      },
      "datastore": "running",
      "edit": [
        {
          "target": "/tapi-common:context/tapi-connectivity:connectivity-context/tapi-connectivity:connection[tapi-connectivity:uuid='c6b01568-5508-3bf1-a2f5-67caf945bda4']",
          "operation": "delete"
        }
      ]
    }
  }
}

Note: Listen to the NETCONF stream notifications for impacted paths to do operations.

The following is an example to understand which of the API to call:

Sample notification:

{
  "ietf-restconf:notification" : {
    "eventTime" : "2024-03-20T04:43:53.910+00:00",
      "datastore" : "running",
      "changed-by" : {
        "username" : "admin",
        "session-id" : 0,
        "source-host" : "127.0.0.1"
      },
      "edit" : [ {
        "target" : "/tapi-common:context/tapi-topology:topology-context/topology[uuid=‘abc’]/node[uuid=‘xyz’]”,
        "operation" : "create"
      } ]
    }
  }

Here use node uuid(‘xyz’) and topology uuid(‘abc’) from the notification target path in /restconf/data/tapi-common:context/tapi-topology:topology-context/topology={uuid}/node API to fetch the complete node "ietf-netconf-notifications:netconf-config-change"