Working with Cisco Support APIs using Python (Part I)

Now a days the buzzword is consume everything using automation through programming. And one way of the consumption is achieved by using REST API and JSON. Let's talk about one such API provided by Cisco - Support APIs.

What is Cisco Support APIs? Cisco's own definition is - Cisco Support APIs allows us to programmatically access and consume Cisco Support data in the cloud in a simple, secure, and scalable manner.

Let's make our own easily explainable definition - We have a Cisco Catalyst Switch; we want to know detail information about our switch like - bug lists, end-of-life data, recommended software suggestions etc. The Cisco Support APIs allows us to manage all those above and much more by consuming their support api's from cloud.

Before going further on I need to introduce two URLs which is required to follow through this blog post - 
API Console Administration

Cisco only provide access to the support apis to customers who have valid support contacts with Cisco for the products they are using. So, a user/customer account (theirs cisco.com login account) must be enabled support api access by Cisco. It can be easily done by contacting your Cisco sales representative. Or a simple guidance for API onboarding is provided by Cisco - https://developer.cisco.com/site/support-apis/.

When one's cisco.com login is enabled for support API, we will login to the https://apiconsole.cisco.com and administer the API keys/tokens which is required for authentication when we make an API call.

After login to the portal we will go to "My Apps & Keys" and "Register a New App". A screenshot is provided below - 


01 - Register APP
01 - Register APP

Now we will register a new app using settings below.

02 - Create App
02 - Create App

The important choice we need to make is - "OAuth2.0 Credentials grant type - Client Credentials" and select the APIs which we want to use. After creating this APP my settings looks like below (all the key/client secret removed which is used for API authentication and user account specific) - 

03 - App Information
03 - App Information

One can also see which APIs I have selected for this App. We can also edit, delete or add apis to the app using corresponding button.

Token generation for making API call

When we create the above App we got a key and client secret. We will use those info to create a token which will be used when making the API calls. The tokens created has a lifetime of 1 hours defined by Cisco. After 1 hour we need to create those token again. The same token can be used for any APIs that is added into the App.

We will use linux (Debian) and curl command to generate the token. The command is shown below (actual key/client_id, client_secret and access_token removed) - 

!!! demo123 - key/client_id; test123 - client_secret; from the App
# curl -k -X POST "https://cloudsso.cisco.com/as/token.oauth2?client_id=demo123&client_secret=test123&grant_type=client_credentials" | python -m json.tool

{
    "access_token": "token123",
    "token_type": "Bearer",
    "expires_in": 3599
}
!!! token123 - the Cisco generated token after the http post call

Now we have the token in hand and time to make some actual API calls.

Calling Support API Endpoints

In programming we are used to say; try to print "Hello World" first when you try to learn something. Let's do that with support api - 

# curl -k -H 'Authorization: Bearer test123' 'https://api.cisco.com/hello/' | python -m json.tool
!!! Json response from Hello API Call
{
    "helloResponse": {
        "response": "Hello World!"
    }
}

Now we can proceed further on as we have verified our authentication and authorization to make api calls towards support api is working.

We have a switch with serial number - 'serial123' (actual serial removed). We want to know the actual product information for that serial number. We will make the below api call - (the api returns a long json output; we will only cover the important fields in that json output) -

# curl -k -H 'Authorization: Bearer token123' 'https://api.cisco.com/product/v1/information/serial_numbers/serial123?responseencoding=json' | python -m json.tool

!!! Json response from API  call
{
            "id": "2",
            "sr_no": "serial123",
            "base_pid": "WS-C2960X-24PS-L",
            "orderable_pid": "WS-C2960X-24PS-L",
            "product_name": "Cisco Catalyst 2960X-24PS-L Switch",
            "product_type": "SWITCH",
            "product_series": "Cisco Catalyst 2960-X Series Switches",
            "product_category": "Switches",
            "product_subcategory": "C2960XSERIES",
            "release_date": "2013-05-24",
            "orderable_status": "O",
            "dimensions": {
                "dimensions_format": "",
                "dimensions_value": ""
            },
            "weight": "",
            "form_factor": "",
            "product_support_page": "http://www.cisco.com/content/en/us/support/switches/catalyst-2960x-24ps-l-switch/model.html",
            "visio_stencil_url": "",
            "rich_media_urls": {
                "small_image_url": "",
                "large_image_url": "http://www.cisco.com/content/dam/en/us/products/switches/ps5718/ps12995/prod_big.jpg"
            }
}

We have gathered information like pid, product_name, release_date, product_support_page etc. by making the api call.

Now we will check the support status of the switch - whether we have a support contract in place for the switch.

# curl -k -H 'Authorization: Bearer token123' 'https://api.cisco.com/sn2info/v2/coverage/status/serial_numbers/serial123?responseencoding=json' | python -m json.tool

!!! Json response from API  call
{
    "serial_numbers": [
        {
            "sr_no": "serial123",
            "is_covered": "YES",
            "coverage_end_date": ""
        }
    ]
}

We can see that our switch has a support contract with Cisco.

Let's try another way of calling these APIs. Our switch has a product id (PID) which is - WS-C2960X-24PS-L. We want to get the current recommended operating system version that is released by Cisco (the api returns a long json output; we will only cover the important fields in that json output).

# curl -k -H 'Authorization: Bearer token123' 'https://api.cisco.com/software/suggestion/v2/suggestions/software/productIds/WS-C2960X-24PS-L?pageIndex=1&contentType=json' | python -m json.tool

!!! Json response from API  call
{
            "id": "2",
            "product": {
                "basePID": "WS-C2960X-24PS-L",
                "mdfId": "284795736",
                "productName": "Catalyst 2960X-24PS-L Switch",
                "softwareType": "IOS Software"
            },
            "suggestions": [
                {
                    "id": "1",
                    "isSuggested": "Y",
                    "releaseFormat1": "15.2.7E6",
                    "releaseFormat2": "15.2(7)E6",
                    "releaseDate": "25-Mar-2022",
                    "majorRelease": "15.2",
                    "releaseTrain": "15.2E",
                    "releaseLifeCycle": "MD",
                    "relDispName": "15.2.7E6",
                    "trainDispName": "",
                    "images": [
                        {
                            "imageName": "c2960x-universalk9-mz.152-7.E6.bin",
                            "imageSize": "26777600",
                            "featureSet": "UNIVERSAL",
                            "description": "",
                            "requiredDRAM": "128 MB",
                            "requiredFlash": "64 MB"
                        },
                        {
                            "imageName": "c2960x-universalk9-tar.152-7.E6.tar",
                            "imageSize": "41553920",
                            "featureSet": "UNIVERSAL WITH WEB BASED DEV MGR",
                            "description": "",
                            "requiredDRAM": "128 MB",
                            "requiredFlash": "64 MB"
                        }
                    ],
                    "errorDetailsResponse": null
                }
            ]
}

From above we have gathered information like the current recommended software release for PID - WS-C2960X-24PS-L is 15.2(7)E6 and also all the details about that version.

Let's try to find the End-Of-Life (EOL) information for PID - WS-C2960X-24PS-L (the api returns a long json output; we will only cover the important fields in that json output). 

# curl -k -H 'Authorization: Bearer token123' 'https://api.cisco.com/supporttools/eox/rest/5/EOXByProductID/1/WS-C2960X-24PS-L?responseencoding=json' | python -m json.tool

!!! Json response from API  call
{
            "EOLProductID": "WS-C2960X-24PS-L",
            "ProductIDDescription": "Catalyst 2960-X 24 GigE PoE 370W, 4 x 1G SFP, LAN Base",
            "ProductBulletinNumber": "EOL13603",
            "LinkToProductBulletinURL": "https://www.cisco.com/c/en/us/products/collateral/switches/catalyst-2960-x-series-switches/eos-eol-notice-c51-744432.html",
            "EOXExternalAnnouncementDate": {
                "value": "2020-10-31",
                "dateFormat": "YYYY-MM-DD"
            },
            "EndOfSaleDate": {
                "value": "2022-10-31",
                "dateFormat": "YYYY-MM-DD"
            },
            "EndOfSWMaintenanceReleases": {
                "value": "2023-10-31",
                "dateFormat": "YYYY-MM-DD"
            },
            "EndOfSecurityVulSupportDate": {
                "value": "2027-10-31",
                "dateFormat": "YYYY-MM-DD"
            },
            "EndOfRoutineFailureAnalysisDate": {
                "value": "2023-10-31",
                "dateFormat": "YYYY-MM-DD"
            },
            "EndOfServiceContractRenewal": {
                "value": "2027-01-29",
                "dateFormat": "YYYY-MM-DD"
            },
            "LastDateOfSupport": {
                "value": "2027-10-31",
                "dateFormat": "YYYY-MM-DD"
            },
            "EndOfSvcAttachDate": {
                "value": "2023-10-31",
                "dateFormat": "YYYY-MM-DD"
            },
            "UpdatedTimeStamp": {
                "value": "2022-11-27",
                "dateFormat": "YYYY-MM-DD"
            },
            "EOXMigrationDetails": {
                "PIDActiveFlag": "Y",
                "MigrationInformation": "Catalyst 9200L 24-port PoE+, Base Switch",
                "MigrationOption": "Enter PID(s)",
                "MigrationProductId": "C9200L-24P-4G",
                "MigrationProductName": "",
                "MigrationStrategy": "",
                "MigrationProductInfoURL": ""
            },
            "EOXInputType": "ShowEOXByPids",
            "EOXInputValue": "WS-C2960X-24PS-L "
}

From above we can see all the details about EOL information about our PID - when Cisco declared EOL and bulletin number, different dates concerning support for software and hardware and also the Cisco recommended migration switch models when it is time to purchase a new switch.

That's it for today. I have just covered a fraction of support API's provided by Cisco. It is strongly recommended to visit the API-Documentation page and read the documentation to find the APIs that in required for your environment.

I have just shown the raw usage of APIs using curl which output JSON data. Stay tuned for Part II of the blog where JSON data will be transformed using Python for more practical use case.
Location: Täby, Sweden

Comments

Post a Comment

Popular posts from this blog

Fortigate firewall AAA Configuration for management with TACACS+ protocol and Cisco ISE

Image
In this blog I will write about how to implement AAA services in Fortigate firewalls using Cisco ISE as an authentication server with TACACS+ protocol. First good to know our limitations. AAA means - Authentication (supported by ISE TACACS+), Authorization (partially supported by ISE TACACS+; Fortigate implements Admin-Profiles; so what a user can/cannot do is defined locally in the firewall with "Admin Profiles"; ISE just instructs the firewall to allocate one of those profiles), Accounting (not supported; instead configure syslog to get accounting data, Fortigate firewalls generate syslog messages for configuration changes made by a user). Let's jump to our configuration. Our topology is very simple; one Fortigate firewall and Cisco ISE server connected with the same management network which looks like below -  01 - Network Topology We have a management network 192.168.199.0/24. The firewall is at  .230  and Cisco ISE is at  .49  IP address. We are running...
Read more

Stacking switches Part - VI (Dell OS10 VLT - Virtual Link Trunking)

Image
In this blog I will configure MLAG (multi chassis link aggregation) for Dell OS10 switches. As every other vendor choses a fancy name of their implementation of MLAG; Dell is no exception to this. Dell calls their implementation VLT - Virtual Link Trunking . Let's look at our network topology - Two Dell OS10 switches will run peering between them and will run VLT/MLAG between them. Two Debian 10 linux machine will be connected with LACP bonding with both switches. They will simulate the client connection. Our topology looks like below - 01 - Dell OS10 VLT Topology Let's look at some terminology before configuration - VLT peer – The two switches participating in VLT are peer to each other. In a VLT domain a maximum of two switches are allowed. VLT interconnect (VLTi) – VLTi synchronizes state information between VLT peers. It synchronizes layer 2 and layer 3 control-plane information. These state/control-plane information includes MAC table, ARP table, IPv6 neighbors etc. VLT ...
Read more

Network device configuration management with Oxidized (Basic)

Image
I always like to work with open source tools. As a network engineer, we need to maintain a device configuration management system where we take backup of configuration for different networking devices like routers, switches, firewalls etc. We want to have our backups ready so that we can restore a device configuration when a device fails or replace with new one or for auditing purpose to track recent configuration changes. Today I will talk about such a open source tools named - Oxidized. Interested readers can have a look at it's GitHub page . It is a network configuration management tool with support for diverse networking equipments. Oxidized is developed with programming language Ruby. It is very configurable, extensible and can be integrated with management tools like Librenms . I will do a two part blog about Oxidized. In this part I will cover basic setup of Oxidized and start taking configuration backup of networking equipments. Network Topology Our topology l...
Read more