Cisco Optical Network Controller TAPI Northbound Interface

Cisco Optical Network Controller acts as an optical domain controller and exposes a standard T-API Northbound interface (NBI) towards northbound clients such as Hierarchical Controller. The TAPI NBI exposes standard RESTCONF and NETCONF interfaces to northbound clients. Any SDN-C client such as Hierarchical Controller can communicate with Cisco Optical Network Controller TAPI NBI Server (SDN-C) using any one these protocols and exchange TAPI model information.

TAPI Models

TAPI specification is based on the Open Networking Foundation's (ONF) Core Information Model (CIM) and is defined using UML. The specification is also mapped from UML to YANG modelling language. Cisco Optical Network Controller NBI supports TAPI Version 2.1.3.

The list of YANG models composing the TAPI information model can be found in the table below.

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:

• The retrieval operations listed in this document covers 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.
• Cisco Optical Network Controller TAPI NBI does not support TAPI standard notifications via notification-context. It only support NETCONF model notifications

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 supported by TAPI while the layer-protocol-qualifier indicates the sub-layer supported within a specific technology. The following table indicates the network layers 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 utilizing the Server-Sent Events transport strategy. Notifications are generated whenever any data changes such as Create, Update or Delete happens 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

Notification is generated when object is created in the TAPI CDB. 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

Notification is generated when object attribute is updated in the TAPI CDB. 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

Notification is generated when object is deleted from the TAPI CDB. 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"