Working with Request and Response Formats

Request

Except for a few file upload APIs, most of the request payloads are in JSON format. For device state and statistics APIs, the predefined JSON query formats are defined in the "Query Format" section in Device State and Statistics. Additional request payloads are explained in each of the API endpoint documents.

Response

The response payload can be in one of the following formats:

Data Block in JSON

This is one of the most common response payloads. It has two top-level JSON objects, "header" and "data". Header contains a generation timestamp, column sections, and a fields section. The "columns" section defines the display name and attributes for the Cisco Catalyst SD-WAN Manager UI data. The "fields" section defines the data type of the response data. You can think of "header:fields" as the object definition of the data.

Here is an example of a response body for /template/policy/list/app:

{
   "header":{
      "generatedOn":1594058538087,
      "viewKeys":{
         "uniqueKey":[

         ],
         "preferenceKey":"grid-PolicyList"
      },
      "columns":[
         {
            "title":"Name",
            "property":"name",
            "hideable":false,
            "dataType":"string"
         },
         {
            "title":"Entries",
            "property":"entries",
            "hideable":true,
            "dataType":"array"
         },
         {
            "title":"Internet Protocal",
            "property":"type",
            "hideable":true,
            "dataType":"string"
         },
         {
            "title":"Reference Count",
            "property":"referenceCount",
            "hideable":true,
            "dataType":"string"
         },
         {
            "title":"Updated By",
            "property":"owner",
            "dataType":"string"
         },
         {
            "title":"Last Updated",
            "property":"lastUpdated",
            "displayFormat":"DD MMM YYYY h:mm:ss A z",
            "inputFormat":"unix-time",
            "dataType":"date"
         }
      ],
      "fields":[
         {
            "property":"name",
            "dataType":"string"
         },
         {
            "property":"type",
            "dataType":"string"
         },
         {
            "property":"description",
            "dataType":"string"
         },
         {
            "property":"listId",
            "dataType":"string"
         },
         {
            "property":"entries",
            "dataType":"array"
         },
         {
            "property":"type",
            "dataType":"string"
         },
         {
            "property":"referenceCount",
            "dataType":"string"
         },
         {
            "property":"owner",
            "dataType":"string"
         },
         {
            "property":"lastUpdated",
            "dataType":"date"
         }
      ]
   },
   "data":[
      {
         "listId":"18d4221c-1c63-4a2b-bf5f-22d252591246",
         "name":"amazon_aws_apps",
         "type":"app",
         "description":"SaaS App List for Amazon AWS",
         "entries":[
            {
               "app":"amazon"
            },
            {
               "app":"amazon-web-services"
            },
            {
               "app":"amazon-instant-video"
            },
            {
               "app":"amazon-cloudfront"
            },
            {
               "app":"amazon-ec2"
            },
            {
               "app":"amazon-s3"
            }
         ],
         "lastUpdated":1593886646494,
         "owner":"system",
         "readOnly":true,
         "version":"3.0",
         "infoTag":"",
         "referenceCount":0,
         "references":[

         ],
         "isActivatedByVsmart":false
      },
      {
         "listId":"4bc7a398-4317-41f2-857b-ead4a94d920e",
         "name":"office365_apps",
         "type":"app",
         "description":"SaaS App List for Office365",
         "entries":[
            {
               "app":"ms-live-accounts"
            },
            {
               "app":"ms-lync"
            },
            {
               "app":"ms-lync-audio"
            },
            {
               "app":"ms-lync-control"
            },
            {
               "app":"ms-lync-video"
            },
            {
               "app":"ms-office-365"
            },
            {
               "app":"ms-office-web-apps"
            },
            {
               "app":"ms-services"
            },
            {
               "app":"ms-teams"
            },
            {
               "app":"ms-teams-audio"
            },
            {
               "app":"ms-teams-media"
            },
            {
               "app":"ms-teams-video"
            },
            {
               "app":"ms-update"
            },
            {
               "app":"outlook-web-service"
            },
            {
               "app":"share-point"
            },
            {
               "app":"skydrive"
            },
            {
               "app":"skype"
            }
         ],
         "lastUpdated":1593886649227,
         "owner":"system",
         "readOnly":true,
         "version":"3.0",
         "infoTag":"",
         "referenceCount":0,
         "references":[

         ],
         "isActivatedByVsmart":false
      }
   ]
}

Task/Process Id for Async API

Some of the APIs take a considerable amount of time to process, so instead of blocking the caller, they will just return with a task/process ID. The caller can use the ID to query the state of the request and retrieve the result. The format for these async APIs is
{taskId: {task-uuid}}, {id: {uuid}} or a similar format.

Object ID for Post API

Some of the Post APIs will return the object ID of the created object. For example: {"policyId":"124a06be-04a7-4037-9fce-e1536dfe9a40"}

Empty Response Body

A few APIs do not have response data in the body. In these cases, the API just contains an empty response body.