SD-AVC REST API

REST API Overview

The REST API provides numerous system functions, including:

  • Displaying information about devices in the SD-AVC network

  • Controlling external sources

  • Displaying information about generic traffic

  • Creating user-defined applications


Note

Using the REST API requires authentication. See Authentication from SD-AVC Network Service.

Table 1. Authentication

POST https://SD-AVC-network-service-address:8443/avc-sd-service/

external-api/login

Acquires an authentication token, enabling use of the REST API.

Authentication from SD-AVC Network Service
Table 2. System

GET /avc-sd-service/external-api/system-info

Displays the SD-AVC version and system times.

Display System Version and System Times

GET /avc-sd-service/external-api/devices

Displays devices in the SD-AVC network.

Display Devices

POST /avc-sd-service/external-api/remove-devices

Removes a device from the SD-AVC network.

Delete Devices from SD-AVC

GET /avc-sd-service/external-api/visibility?period=period

-

GET /avc-sd-service/external-api/visibility/segmentName

?period=period

-

GET /avc-sd-service/external-api/visibility/segmentName/

deviceName?period=period

Display traffic analytics (applications and bandwidth) for the complete SD-AVC network, a specific segement, or a specific device.

Display Traffic Analytics
Table 3. External Sources

POST /avc-sd-service/external-api/external-sources/externalSourceName

Enables or disables receiving data from an external source.

Enable/Disable External Sources

GET /avc-sd-service/external-api/external-sources

Displays status of external sources.

Display Status of External Sources
Table 4. User-defined Applications

POST /avc-sd-service/external-api/app-rules

Create one or more user-defined applications.

Create User-defined Application Rules

GET /avc-sd-service /external-api/app-rules

-

GET /avc-sd-service /external-api/app-rules?sourceId=sourceId

Displays user-defined applications defined by REST API.

Display User-defined Application Rules

GET /avc-sd-service/external-api/app-rules/status

-

GET /avc-sd-service /external-api/app-rules/status[?sourceId=sourceId]

Displays activation status of user-defined applications, per device.

Display User-defined Application Status

DELETE /avc-sd-service /external-api/app-rules

-

DELETE /avc-sd-service /external-api/app-rules?sourceId=sourceId

Deletes a set of user-defined applications.

Delete User-defined Applications
Table 5. Generic Applications

GET /avc-sd-service/external-api/apps/generics

Displays the list of traffic types that contribute to "generic" traffic.

Display Generic Application Traffic Types

Authentication from SD-AVC Network Service

Using the REST API requires a token-based authentication from the SD-AVC network service. To acquire an authentication token:

  1. Send the following HTTP request to the API:

    POST https://SD-AVC-network-service-address:8443/avc-sd-service/external-api/login

    Example: 

    POST https://192.168.0.1:8443/avc-sd-service/external-api/login

    • In the request header, include the following key:

      • Content-Type: application/x-www-form-urlencoded

    • In the request body, include the following keys, providing login credentials:

      • username: username
      • password: password

  2. The API response body provides an authentication token. Use the token to authorize REST API calls to the SD-AVC network service.


    Note

    The token expires after 12 hours.

    Example: 

    {"token":"Bearer eyJhbGciOiJIUzUxMiJ9.eyJqdGkiOiJhYjZkGGUxOS0zMmU3LTRlY2ItYWQ5OC
1kYmVmZTdjZjE5YzYiLCJzdWIiOiJsYWIiLCJleHAiOjE1MzAwMqk1MzJ9.EfP3wd4fZbWrOQ6Skh-I0
bbPffF4NaruB-o_OV0EQ7fwMwfmkUUNP00R58fRGKkYWR3tQu8HjoVDp37EPtDl5Q"}

  3. Use this token in the "Authorization" request header field of each HTTP request.

System

System Overview

The REST API can display information about the SD-AVC system, and change the configuration.

Display System Version and System Times

API

GET /avc-sd-service/external-api/system-info

Description

Displays:

  • Current time: Time in UNIX format.

  • System uptime: SD-AVC uptime in milliseconds.

  • SD-AVC version

  • Cloud Connector status (enabled/disabled, errors, warnings)

  • Office 365 Connector status (enabled/disabled, errors, warnings)

Example Response

{
    "systemTime": "2019-06-26T12:19:02Z",
    "systemUpTimeSec": "13490106",
    "version": "4.0.0",
    "cloudConnector": {
        "isEnabled": true,
        "error": [],
        "warning": []
    },
    "o365Connector": {
        "isEnabled": true,
        "error": [],
        "warning": []
    },
    "cloudStage": "test"
}

Display Devices

API

GET /avc-sd-service/external-api/devices

Description

Displays the devices in the SD-AVC network, organized by segment, in JSON format. The response includes errors and warnings, and additional information per device.

Response

The output shows errors and warnings for:

  • total network

  • each segment

  • each device

Example Response

The example represents a network with one segment (datacenter-01) and one device (asr-device-100) within that segment.

{  
   "total":{  
      "connection":{  
         "error":[],
         "warn":[]
      },
   },
   "segments":[  
      {  
         "name":"datacenter-01",
         "connection":{  
            "error":[],
            "warn":[]
         },
         "devices":[  
            {  
               "name":"asr-device-100",
               "ip":"192.168.1.0",
               "connection":{  
                  "error":[],
                  "warn":[]
               }
            }
         ]
      }
   ]
}

Delete Devices from SD-AVC

API

POST /avc-sd-service/external-api/remove-devices

Description

Removes a device from the SD-AVC network. Specify the device and segment in the body.

Body

{  
   "devices":[  
      {  
         "name":"device-name-1",
         "ip":"address-1"
      },
      {  
         "name":"device-name-2",
         "ip":"address-2"
      }
   ],
   "segment":"segment-name"
}

Example Body

{  
   "devices":[  
      {  
         "name":"dev1",
         "ip":"10.10.10.10"
      },
      {  
         "name":"dev2",
         "ip":"10.10.10.11"
      }
   ],
   "segment":"dnac"
}

Example Response

{"success":true,"message":"2 devices from segment dnac were deleted successfully"}

Display Traffic Analytics

API

GET /avc-sd-service/external-api/visibility?period=period

-

GET /avc-sd-service/external-api/visibility/segmentName?period=period

-

GET /avc-sd-service/external-api/visibility/segmentName/deviceName?period=Period

Description

Displays traffic analytics (applications and bandwidth) for the complete SD-AVC network, a specific segment, or a specific device. Optionally, specify a period for the analytics. The response includes:

  • Application name and bandwidth (bytes) used by the application

  • Total bandwidth (bytes) used

Table 6. Properties

Property

Description

segmentName

(Optional)

Specifies a segment. Response includes only analytics from this segment.

deviceName

(Optional)

Specifies a device. Response includes only analytics from this device.
period

Use ?period=period to specify the period to include in the analytics.

Possible values for period: 120, 720, 1440, 2880 minutes (These correspond to 2, 12, 24, and 48 hours.)

Example:

In this example, the period is set to 24 hours (1440 minutes).

GET /avc-sd-service/external-api/visibility/datacenter01/device-300?period=1440

{
"apps": [{
"name": "vmwarevsphere",
"bandwidth": 226331127989634
}, {
"name": "telepresencecontrol",
"bandwidth ": 146787859067274
}, {
"name": "unknown",
"bandwidth": 132586088501412
}],
"totalBandwidth": 505705075558320
}

Cloud Connector

Connect to Cloud Connector

API:

POST /avc-sd-service/external-api/cloud/authorize

Description:

Connect to the Cloud Connector, using credentials. See Cloud Connector.

Example:

cisco_client_id=YOUR_CLIENT_ID&cisco_client_secret=YOUR_CLIENT_SECRET&cloud_organization_name=
ORAGANIZATION_NAME&cloud_data_affinity=usa&telemetry_enabled=1

Example Responses:

{"success":"AUTH_SUCCESS"}

or

{“error”:  “INVALID_CREDENTIALS”}

Disable Cloud Connector

API:

POST /avc-sd-service/external-api/cloud/disable

Description:

Disables the Cloud Connector. See Cloud Connector.

Example Response:

{ “success”: true }

Remove Cloud Connector Credentials

API:

POST /avc-sd-service/external-api/cloud/removeCredentials

Description:

Clears the credentials that have been entered for Cloud Connector.

Example Response:

{ “success”: true }

Display Current Cloud Configuration

API:

GET /avc-sd-service/external-api/cloud/getCurrentCloudConfig

Description:

Displays the current configuration for Cloud Connector.

Example Response:

{"cisco_client_id":{"key":"cisco_client_id","currentValue":"MY_CLIENT_ID","defaultValue":""},
"cloud_credentials_renew_threshold":{"key":"cloud_credentials_renew_threshold","currentValue":"90"},
"cloud_credentials_renew_time":{"key":"cloud_credentials_renew_time","currentValue":"1561547912794","defaultValue":"0"},
"cloud_data_affinity":{"key":"cloud_data_affinity","currentValue":"usa"},"cloud_enabled":{"key":"cloud_enabled",
"currentValue":"1","defaultValue":"0"},"cloud_organization_name":{"key":"cloud_organization_name","currentValue":"CSCO",
"defaultValue":""},"telemetry_enabled":{"key":"telemetry_enabled","currentValue":"1"}}

Display Cloud Data

API:

GET /avc-sd-service/external-api/app-rules?sourceId=PP_Extension

Description:

Displays the currently collected cloud data (rules, server names, sockets, and so on).

Example Response:

[{
    "sourceId": "PP_Extension",
    "rules": [{
        "allSegments": true,
        "rules": [{
                "appName": "slack",
                "serverNames": ["slack-redir.net",
                    "www.slack-redir.net"
                ],
                "L3L4": [{
                    "ipAddresses": ["34.204.245.22"],
                    "ports": [443],
                    "l4Protocol": "TCP"
                }]
            },
            {
                "appName": "facebook",
                "L3L4": [{
                    "ipAddresses": [
                        "31.13.24.0/21",
                        "31.13.64.0/19"
                    ]
                }]
            }
        ]
    }]
}]

External Sources

External Sources Overview

External sources provide additional application information that SD-AVC uses for classifying network traffic. They are managed by Cloud Connector. To use external sources, ensure that Cloud Connector is enabled. See Cloud Connector.

Enable/Disable External Sources

API

POST /avc-sd-service/external-api/external-sources/externalSourceName

Description

Enables or disables receiving data from an external source.

Table 7. Properties

Property

Description

externalSourceName

(Mandatory)

Name of the external source.

Note 

In this release, the only external source to specify is "ms-office-365". To use this external source, Cloud Connector must be enabled. See Cloud Connector.

start

stop

In the JSON body of the command, enables or disables the external source.

Examples

POST /avc-sd-service/external-api/external-sources/ms-office-365

{  
   "action":"start"
}
POST /avc-sd-service/external-api/external-sources/ms-office-365

{  
   "action":"stop"
}

Display Status of External Sources

API

GET /avc-sd-service/external-api/eternal-sources

Description

Displays external sources and their status: true = enabled, false = disabled.

Example

GET /avc-sd-service/external-api/external-sources

Example Response

In this example, the MS Office 365 Web Service, an external source, is enabled.

{
  "sources": [{
    "ms-office-365":true
  }]
}

User-defined Applications

User-defined Applications Overview

Network devices operating with SD-AVC use Cisco NBAR2 and other tools to identify network traffic. The composite of information that NBAR2 uses to identify a network applications is called an "application" (or a "protocol" in the Protocol Packs released periodically by Cisco). User-defined applications may be specified on individual devices by CLI, or network-wide using SD-AVC.

Each application includes:

  • Signature: Details that identify the network application

  • Attributes: Assigned characteristics of the application, such as business-relevance, used for visibility and QoS policy.

Table 8. Application Types

Application Type

Description

Protocol Pack applications

Standard applications provided by Cisco in a Protocol Pack.

User-defined applications on individual devices

Defined by CLI on individual devices, sometimes called custom protocols.

Network-wide user-defined applications

Defined by SD-AVC REST API.

These appear on the SD-AVC Dashboard > External Sources page.

SD-AVC User-defined Applications

SD-AVC can provision user-defined applications at the network level, available for all participating devices in the network. In effect, this is similar to adding user-defined applications manually on each device.

Create User-defined Application Rules

API

POST /avc-sd-service/external-api/app-rules

Description

Defines one or more user-defined applications.

Body

Body must include the full set of user-defined applications. Executing the API overwrites any currently defined user-defined applications for the specified source (sourceId). 

{
    "sourceId": string,
    "rules": [{
        "allSegments": boolean,
        "segment": string,
        "rules": [{
            "appName": string,
            "serverNames": [string],
            "L3L4": [{
                "ipAddresses": [string],
                "ports": [integer(s) or range],
                "l4Protocol": string,
                "vrf": string
            }],
            "attributes": {
                "category": string,
                "sub-category": string,
                "application-group": string,
                "business-relevance": string,
                "traffic-class": string,
                "application-set": string
                }
        }]
    }]
}
Table 9. Top-level Properties

Property

Description

sourceId

(Mandatory)

ID of the external source.

Note 

In the initial release of the REST API, only one source is supported.

rules

(Mandatory)

Contains complete list of the user-defined application rules.

Note 

This property contains a sub-property also called rules.
Table 10. Sub-properties of rules

Property

Description

allSegments

(Must include either allSegments or segment.)

Set to true to apply the user-defined applications to all segments, not only one segment.

Possible values: true, false (default)

segment

(Must include either allSegments or segment.)

List of user-defined application rules for a specific SD-AVC segment.

rules

(Mandatory)

List of segment rules.
Table 11. Sub-properties of rules > rules

Property

Description

appName

(Mandatory)

Name of user-defined application, reflecting name of the network application.

Note 

Do not use a name that conflicts with an existing application, such as one defined in the Protocol Pack.

serverNames

(Must include at least one of serverNames, L3L4, and attributes.)

List of all server names (FQDNs, SNIs, …) for the network application.

Note 

Server names are case-sensitive.

L3L4

(Must include at least one of serverNames, L3L4, and attributes.)

List of all IP-based rules.

(See sub-properties below.)

attributes

(Must include at least one of serverNames, L3L4, and attributes.)

Attributes to assign to the application.

(See sub-properties below.)
Table 12. Sub-properties of rules > rules > L3L4

Property

Description

IpAddresses

(Mandatory)

List of IPs. Can be both normal IP and subnet (using CIDR notation).

ports

Port(s) or port range.

If this property is defined, you must also include l4protocol.

Examples: 

"ports": [23]
"ports": [23,24]
"ports": [23, "25-30"]

l4Protcol

Transport layer protocol.

If this property is defined, you must also include ports.

Possible values: TCP, UDP, TCP-UDP

vrf

VRF name.
Table 13. Sub-properties of rules > rules > attributes

Property

Description

application-set

(Must include at least one of serverNames, L3L4, and attributes.)

Attributes to assign to the application.

application-group

(Defining a partial list of attributes is supported. If attributes is included, must include at least one of these properties.)

category

sub-category

traffic-class

business-relevance

Response

Response code 200 indicates success.

In case of failure, the response body provides information about the reason for failure.

Example 1: Single domain name

This example shows:

  • 1 network segment: datacenter01

  • 1 user-defined application: myDocs

  • 1 server name

  • No attributes specified

{
  "sourceId": "mySource",
  "rules": [{
    "segment": "datacenter01",
    "rules": [{
      "appName": "myDocs",
      "serverNames": [
        "www.myApp.com"
      ]
    }]
  }]
}

Example 2: Three IP addresses and ports

This example shows:

  • 1 network segment: datacenter01

  • 1 user-defined application: myDocs

  • 3 IP addresses and 3 ports

  • No attributes specified

{
    "sourceId": "mySource",
    "rules": [{
        "segment": "datacenter01",
        "rules": [{
            "appName": "myDocs",
            "L3L4": [{
                    "ipAddresses": ["2.2.2.2"],
                    "ports": [20],
                    "l4Protocol":"TCP"
                },
                {
                    "ipAddresses": ["3.3.3.3"],
                    "ports": [30],
                    "l4Protocol":"TCP"
                },
                {
                    "ipAddresses": ["4.4.4.4"],
                    "ports": [40],
                    "l4Protocol":"TCP"
                }
            ]
        }]
    }]
}

Example 3: Two user-defined applications in one network segment

This example shows:

  • 1 network segment: datacenter01

  • 2 user-defined applications: myDocs and myTelepresence

  • No attributes specified for the myDocs user-defined application

  • business-relevance attribute specified for the myTelepresence user-defined application

  • IP address with subnet specified

  • Individual ports and a range of ports

{
  "sourceId": "mySource",
  "rules": [{
    "segment": "datacenter01",
    "rules": [{
        "appName": "myDocs",
        "serverNames": [
          "www.myApp.com"
        ],
        "L3L4": [{
          "ipAddresses": ["10.1.1.0/24", "2.2.2.2"],
          "ports": [23, 34, "37-42"],
          "l4Protocol": "TCP",
          "vrf": "vrf1"
        }]
      },
      {
        "appName": "myTelepresence",
        "L3L4": [{
          "ipAddresses": ["2.2.2.2"],
          "ports": [35],
          "l4Protocol": "TCP"
        }],
        "attributes": {
          "business-relevance": "business-relevant"
        }
      }
    ]
  }]
}

Example 4: User-defined applications in two network segments

This example shows:

  • 2 network segments: datacenter01, datacenter02

  • 3 user-defined applications: myDocs, myTelepresence, myEnterpriseIM

  • No attributes specified for: myDocs, myEnterpriseIM

  • business-relevance attribute specified for myTelepresence

  • IP address with subnet specified

  • Individual ports and a range of ports

{
  "sourceId": "mySource",
  "rules": [{
      "segment": "datacenter01",
      "rules": [{
          "appName": "myDocs",
          "serverNames": [
            "www.myDocs.com"
          ],
          "L3L4": [{
            "ipAddresses": ["10.1.1.0/24", "2.2.2.2"],
            "ports": [23, 34, "37-42"],
            "l4Protocol": "TCP",
            "vrf": "vrf1"
          }]
        },
        {
          "appName": "myTelepresence",
          "L3L4": [{
            "ipAddresses": ["2.2.2.2"],
            "ports": [35],
            "l4Protocol": "TCP"
          }],
          "attributes": {
            "business-relevance": "business-relevant"
          }
        }
      ]
    },
    {
      "segment": "datacenter02",
      "rules": [{
        "appName": "myEnterpriseIM",
        "serverNames": [
          "www.myEnterpriseIM.com"
        ],
        "L3L4": [{
          "ipAddresses": ["2.2.2.10"],
          "ports": [23],
          "l4Protocol": "TCP"
        }]
      }]
    }
  ]
}

Example 5: Using allSegments and specific network segments

This example shows:

  • 2 user-defined applications (myDocs, myTelepresence) for all network segments, using allSegments

  • User-defined application (myEnterpriseIM) only for 1 network segment: datacenter02

  • 3 user-defined applications: myDocs, myTelepresence, myEnterpriseIM

  • No attributes specified for: myDocs, myEnterpriseIM

  • business-relevance attribute specified for myTelepresence

  • IP address with subnet specified

  • Individual ports and a range of ports

{
  "sourceId": "mySource",
  "rules": [{
      "allSegments": true,
      "rules": [{
          "appName": "myDocs",
          "serverNames": [
            "www.myApp.com"
          ],
          "L3L4": [{
            "ipAddresses": ["10.1.1.0/24", "2.2.2.2"],
            "ports": [23, 34, "37 - 42"],
            "l4Protocol": "TCP",
            "vrf": "vrf1"
          }]
        },
        {
          "appName": "myTelepresence",
          "L3L4": [{
            "ipAddresses": ["2.2.2.2"],
            "ports": [35],
            "l4Protocol": "TCP"
          }],
          "attributes": {
            "business-relevance": "business-relevant"
          }
        }
      ]
    },
    {
      "segment": "datacenter02",
      "rules": [{
        "appName": "myEnterpriseIM",
        "serverNames": [
          "www.myEnterpriseIM.com"
        ],
        "L3L4": [{
          "ipAddresses": ["2.2.2.10"],
          "ports": [23],
          "l4Protocol": "TCP"
        }]
      }]
    }
  ]
}

Display User-defined Application Rules

API

GET /avc-sd-service /external-api/app-rules

GET /avc-sd-service /external-api/app-rules?sourceId=sourceId

Description

Displays the user-defined applications defined by REST API.

Response

The response lists the user-defined applications defined for a single source or all sources. The response body uses the same JSON structure as POST.

If no sourceId is specified, the response lists the user-defined applications for all sources.

If sourceId is specified, the response lists the user-defined applications for the specified source. The sourceId is user-defined by POST when defining user-defined applications.


Note

In the initial release of the REST API, only one source is supported.

Display User-defined Application Status

API

GET /avc-sd-service/external-api/app-rules/status

GET /avc-sd-service /external-api/app-rules/status[?sourceId=sourceId]

Description

The SD-AVC network service sends the user-defined applications defined by REST API to the devices in the network. This API displays the activation status of the applications, per device.

If sourceId is specified, the output is limited to that source.The sourceId is user-defined by POST when defining user-defined applications.


Note

In the initial release of the REST API, only one source is supported.

Response

The response lists each network device, arranged by segment. For each device:

  • ID/version of application rules currently loaded on the device

  • Status: SUCCESS, FAILED, IN-PROGRESS

Delete User-defined Applications

API

DELETE /avc-sd-service /external-api/app-rules

DELETE /avc-sd-service /external-api/app-rules?sourceId=sourceId

Description

Deletes a set of user-defined applications.

If no sourceId is specified, deletes the full set of user-defined applications.

If sourceId is specified, deletes the full set of user-defined applications for the specified source. The sourceId is user-defined by POST when defining user-defined applications.


Note

In the initial release of the REST API, only one source is supported.

Response

Response code 200 indicates success.

Generic Applications

Generic Applications Overview

"Generic" network traffic is not attributed to a specific network application. This portion of network traffic reduces the classification index, which is shown in the SD-AVC Dashboard.

Display Generic Application Traffic Types

API

GET /avc-sd-service/external-api/apps/generics

Description

Displays the list of traffic types that contribute to generic traffic. The response is preconfigured - it does not depend on current traffic.

Response

["statistical-conf-audio","rtp-audio","spdy","statistical-p2p","rtp-video","http","statistical-conf-video",
"quic","statistical-download","ssl","unknown","rtp"]