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

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

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

Example Response

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

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":[]
               }
            }
         ]
      }
   ]
}

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"}

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 | deviceAddress]?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

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
}

API:

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

Description:

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

Note	Deprecated in SD-AVC 4.0.0. Use: POST /avc-sd-service/external-api/cloud/configure If continuing to use this deprecated API, do not use it together with the POST /avc-sd-service/external-api/cloud/configure API.

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”}

API:

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

Description:

Disables the Cloud Connector. See Cloud Connector.

Note

Use this API when you have configured Cloud Connector credentials with the "authorize" API: POST /avc-sd-service/external-api/cloud/authorize If you have configured Cloud Connector credentials using the "configure" API... POST /avc-sd-service/external-api/cloud/configure ...then do not use this API to disable Cloud Connector. Instead, use the following "configureSegment" API, specifying "false" for the transmit and receive options: POST /avc-sd-service/external-api/cloud/configureSegment?segment=name See Configure Cloud Connector Credentials.

Example Response:

{ “success”: true }

API:

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

Description:

Clears the credentials that have been entered for Cloud Connector.

Example Response:

{ “success”: true }

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"}}

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"
                    ]
                }]
            }
        ]
    }]
}]

API:

GET https://SD-AVC-network-service-address:8443/avc-sd-service/external-api/cloud/status

GET https://SD-AVC-network-service-address:8443/avc-sd-service/external-api/cloud/status?segment=segmentName

Description:

Display status of the Cloud Connector for the specified segment.

Body:

{
    "cloudConnector": {
        "isEnabled": true,
        "error": []
    }
}

• isEnabled: Cloud status for the segement. Values: true, false

• error: Detected errors.

  • CONNECTIVITY: SD-AVC cannot reach the cloud server. Connectivity problems may include DNS issues, and so on.

  • CREDENTIALS: Credentials for connecting to the cloud server are invalid. For example, the client secret may have expired.

  • INTERNAL_CLOUD: SD-AVC cannot retrieve the cloud rules. The output provides a reason for the error. The stated reason may be helpful when troubleshooting with Cisco technical assistance.

Example Responses:

Cloud Connector enabled, no errors:

{
    "cloudConnector": {
        "isEnabled": true,
        "error": []
    }
}

Cloud Connector enabled, INTERNAL_CLOUD error, with reason:

{
    "cloudConnector": {
        "isEnabled": true,
        "error": [
        {
            id: "INTERNAL_CLOUD",
            reason: ["MINOR_PP"]
        }]
    }
}

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.

API

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

Description

Enables or disables receiving data from an 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"
}

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
  }]
}

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.

API

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

POST /avc-sd-service/external-api/app-rules?segment=segmentName

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
                }
        }]
    }]
} 

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

Response

Response code 200 indicates success.

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

API

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

PUT /avc-sd-service/external-api/app-rules?segment=segmentName

Description

Add a user-defined application to an existing set of applications in a particular segment.

Body

The body must include a single user-defined application. See Create User-defined Application Rules for descriptions of the properties to use for user-defined applications. Executing the API overwrites any currently defined user-defined applications for the specified source (sourceId).

If you use the name (appName field) as an existing user-defined application, this API overwrites the existing application.

Note	If you have configured custom applications using the SD-AVC Dashboard, then you must use the following sourceID: "sdavc_ui_custom_source"

{
    "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
                }
        }]
    }]
} 

Response

Response code 200 indicates success.

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

API

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

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

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

GET /avc-sd-service /external-api/app-rules?segment=segmentName&app=applicationName

Description

Displays the user-defined applications.

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.

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

API

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

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

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

DELETE /avc-sd-service /external-api/app-rules?segment=segmentName&app=applicationName

Description

Deletes a set of user-defined applications.

If no source, segment, or application are specified, the API deletes the full set of user-defined applications.

"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.

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"]