Understanding API calls
API (Application Programming Interface) is a way for one program to interact with another. An API call or API request is a message sent to a server asking an API to provide a service or information.
In our lab setup, since we are interacting with Catalyst Center, the API calls that we are doing through Postman (Client) interacts with the API endpoint present on the Catalyst Center to retrieve some information or to invoke some service (configuration) on the Catalyst Center.
The Intent API is a Northbound REST API that exposes specific capabilities of the Cisco Catalyst Center platform. The RESTful Cisco Catalyst Center Intent API uses HTTPS verbs (GET, POST, PUT, and DELETE) with JSON structures to discover and control the network.
Understanding HTTPS verbs used in the lab:
- POST – We will primarily use POST calls in this lab. POST is used to send data to the CATALYST CENTER server to perform any configuration changes/ updates.
- GET – We will seldom use these; however, it is another important verb. GET is used to ask for information from the Catalyst Center.
Catalyst Center API calls
Create Sites
The first step in configuring automation & assurance is to create Network Hierarchy.
URL - https://{{CatalystCenter-ip}}/dna/intent/api/v1/site
Headers – x-auth-token = {{CatalystCenter_token}}
Example Request Body – This will create an Area named “United States” under Global.
{
"type": "area",
"site": {
"area": {
"name": "United States",
"parentName": "Global"
}
}
}
Example Request Body – This will create an Area named “New York” under Global/United States.
{
"type": "area",
"site": {
"area": {
"name": "New York",
"parentName": "Global/United States "
}
}
}
Create Building and Floors under Sites
Here, we will create buildings and floor under sites.
URL - https://{{CatalystCenter-ip}}/dna/intent/api/v1/site
Headers – x-auth-token = {{CatalystCenter_token}}
Example Request Body – This will create a building named “Penn Plaza” under “Global/United States”
{
"type": "building",
"site": {
"area": {
"name": "New York",
"parentName": "Global/United States"
},
"building": {
"name": "Penn Plaza",
"address": " 250 West 34th Street Manhattan, New York"
}
}
}
Example Request Body – This will create a Floor named “Floor_2” under “Global/United States/New York/Penn Plaza”
{
"type": "floor",
"site": {
"area": {
"name": "New York",
"parentName": "Global/United States"
},
"building": {
"name": "Penn Plaza",
"address": "250 West 34th Street Manhattan, New York"
},
"floor" : {
"name": "Floor_2",
"parentName": "Global/United States/New York/Penn Plaza",
"rfModel": "Cubes And Walled Offices",
"width": 100,
"length": 100,
"height": 10
}
}
}
Create cli and SNMP read/ write credentials
After creating network hierarchy our next task is to create CLI and SNMP read/write credentials which will enable us during device discovery. Note – All the call in this section will be POST calls.
URL - https://{{CatalystCenter-ip}}/dna/intent/api/v2/global-credential
Headers – x-auth-token = {{CatalystCenter_token}}
Example Request Body – This will create a CLI-Credential named “admin-cli” and SNMPv2 read/write credentials.
{
"cliCredential": [
{
"description": "admin-cli",
"username": "admin",
"password": " password",
"enablePassword": " password"
}
],
"snmpV2cRead": [
{
"description": " SNMP read community ",
"readCommunity": "public"
}
],
"snmpV2cWrite": [
{
"description": " SNMP write community ",
"writeCommunity": "private"
}
]
}
Discover Devices
In the previous task we defined global credentials for devices. Now we will use those global credentials to discover devices that are present on the network. We will follow the below steps to discover devices in our network.
- Get CLI id
The first step will be to get the CLI ID of the globally configured CLI credentials that we defined in the last section. We will use that in the discovery process.
Step 1 – Use the following request URL – https://{{CatalystCenter-ip}}/dna/intent/api/v2/global-credential and add the token in Headers section as we did in previous tasks.
Step 2 – Send the request, In the response section go to “cliCredentiali” copy the value for key “id”. Store it in notepad as we will use this value in our next POST call. Similarly copy the “id” value for “snmpV2cRead” and “snmpV2cWrite” key.
- Discover device
URL - https://{{CatalystCenter-ip}}/dna/intent/api/v1/discovery
Headers – x-auth-token = {{CatalystCenter_token}}
Example Request Body – add the cli id that we copied in the previous API call and substitute that in the “globalCredentialIdList” key.
{
"name": "discover-device-1",
"discoveryType": "Range",
"ipAddressList": "198.19.1.2-198.19.1.2",
"protocolOrder": "ssh",
"timeOut": 5,
"retryCount": 3,
"globalCredentialIdList": [
"Add the CLI id here!", "Add the snmp_read id", "Add the snmp_write id"
],
"preferredMgmtIPMethod":"UseLoopBack"
}
Step 4 – Click on Send, you should have got a 202 Accepted response in the response section.
3. Verify whether the devices got discovered
In this section we will verify whether the devices got discovered, for that purpose we will utilise another API call which will be a GET call.
Step 1 – Use the following request URL - https://{{CatalystCenter-ip}}/dna/intent/api/v1/discovery/count and {{CatalystCenter-token}} as token.
Step 2 – Click Send, In the response section the value corresponding to the “response” key should be equivalent to the number of discovery jobs you performed via the previous POST call. Also, to verify in the GUI, go to Tools > Discovery > View All Discoveries.
Assign Devices to site
In the last section we discovered devices, and they are present as Unassigned devices in the inventory. So, we would have to assign them to sites before we can perform automation and assurance capabilities of Catalyst Center.
- Get Site/Building/Floor id where the device is going to be assigned
The first step is to get the siteID where we are going to assign the device.
Step 1 – Use the following request URL - https://{{CatalystCenter-ip}}/dna/intent/api/v2/site and add token in the Headers section
Step 2 – In the response section go to copy the value of key “id” for a specific site hierarchy name and store it in notepad so that it can be used later.
2. Grab the device-id of the device to be assigned
The second step is to get the deviceID, the device we are trying to assign to a site.
Step 1 – Use the following request URL – https://{{CatalystCenter-ip}}/dna/intent/api/v1/network-device and add token in the Headers section.
Step 2 – In the response section, copy the value of key “id” for the device to be assigned to a site and store it so that it can be used later.
3. Assign the device to floor
URL - https://{{CatalystCenter-ip}}/dna/intent/api/v1/networkDevices/assignToSite/apply
Headers – x-auth-token = {{CatalystCenter_token}}
Example Request Body – Add the site ID and device ID values, that we fetched from previous sections and add into the request body.
{
"deviceIds": [
"string"
],
"siteId": "string"
}
Execute the API Call, you should get a 202 Accepted response in the response section. To verify in catalyst Center GUI, go to Provision > Inventory > {site} to see if the device is present.
Deploy DayN template to Device
We will deploy a DayN template onto discovered devices using Template APIs.
- Find the template ID
Step 1 – Use the following URL – https://{{CatalystCenter-ip}}/dna/intent/api/v2/template-programmer/project this will be a GET request, use the token as header as we have for other requests
Step 2 – You should get a 200 OK response. In the response body check for the template name, copy the value for “id” key under the dictionary with template name, this is the template ID that we will use for deploying this template.
- Deploy Template to device
URL - https://{{CatalystCenter-ip}}/dna/intent/api/v1/template-programmer/template/deploy
Headers – x-auth-token = {{CatalystCenter_token}}
Example Request Body – add the template ID in the below request body and execute the AP Call.
{
"forcePushTemplate": false,
"targetInfo":[
{
"id": "198.19.1.2",
"type": "MANAGED_DEVICE_IP"
}
],
"templateId":"Add the template ID here!"
}
Upon execution we will receive a 202 Accepted response, In the response body copy the deployment Id: and save it, for this will be used to check the template deployment status.
- Check Template deployment status
We will check if the template was deployed to the device.
Step 1 – This will be a GET request, Use the following URL.
https://{{CatalystCenter-ip}}/dna/intent/api/v1/template-programmer/template/deploy/status/{Deployement-Id}
In place of Deployment-Id substitute the deployment ID that you saved from the last call.
Step 2 – You should get a 202 Accepted message. In the response body check the status as SUCCESS if not re-send the request again to check for the latest status.
Get Assurance Data
Here we will see how to use Assurance API to fetch health related data for our network
- Use the following URL - https://{{CatalystCenter-ip}}/dna/intent/api/v1/network-device/count, to get the total device count from CatalystCenter, add token. You should get 200 OK response. We will see the total device count in the response
- Use the following URL - https://{{CatalystCenter-ip}}/dna/intent/api/v1/network-health to get health data for all the network devices.
- Use the following URL - https://{{CatalystCenter-ip}}/dna/intent/api/v1/client-health to get client health data across the network.
- Use the following URL – https://{{CatalystCenter-ip}}/dna/intent/api/v1/issues to get issues affecting the network
