API Programmability - Part 1: The Basics

5 minute read

Introduction

One of the most difficult parts in a Network Automation journey is collecting the data you need.  Many developers spend hours creating parsers to make data that is returned from devices usable.  After creating a parser to extract data from one vendor’s device it must be adjusted for syntax on other vendors, platforms, or even differences in software versions.  IP Fabric extracts your important network data directly from the devices and places it in our vendor neutral data models which removes this parsing burden from your development teams.  All this information is searchable in our platform without the need for memorizing numerous different commands.

Did you know that all this parsed data in IP Fabric is also easily accessible via the API?  Today I will be sharing some basic Python code examples that will help you get started with your automation journey.  We will be using the Python requests module so you can easily translate these into other languages.  In future blog posts we will focus on the Python ipfabric package.

Prerequisites

Before we begin here are some of the basics you will need to follow along:

  • IP Fabric (3.7.0 or higher which supports API Token)
  • Python 3 (Any version should do)
  • pip (for python package installation)
  • IDE or Notepad++ (Optional)

Creating your API Token

First head into your IP Fabric’s GUI and select Settings > API Tokens.  This will display all current tokens and allow us to create a new one.

After clicking “Create Token” you will be prompted for some information.  It is important to copy the generated token prior to selecting create, once created it cannot be displayed again.  Descriptions are helpful and recommend, although not required, for managing your tokens.  You can specify a date that it will expire and the permissions it has.  For most of these blog posts we will only require Read and Discovery.

Python Setup

After installing python, we will be using only the requests package for our examples as it is the most widely used and a great starting point for our project.  There are many different open-source packages that provide the same functionality as requests like httpx and urllib3, so feel free to do some research and select the best one for your project.  To install requests run:

`pip3 install requests`

Let’s Get Coding

import requests

session = requests.Session()
session.headers.update({'Content-Type': 'application/json', 'X-API-Token': 'TOKEN'})

payload = {
    "columns": [
        "id",
        "siteName",
        "siteKey",
        "devicesCount",
        "usersCount",
        "stpDCount",
        "switchesCount",
        "vlanCount",
        "rDCount",
        "routersCount",
        "networksCount"
    ],
    "snapshot": "$last"
}
r = session.post('https://demo3.wordpress-625423-2416527.cloudwaysapps.com/api/v1/tables/inventory/sites', json=payload)
print(r.json()['data'][0])


"""
{'id': '1111118694', 'siteName': 'HWLAB', 'siteKey': '1111118694', 'devicesCount': 22, 'usersCount': 13, 'stpDCount': 2, 'switchesCount': 8, 'vlanCount': 131, 'rDCount': 3, 'routersCount': 6, 'networksCount': 61}
"""

In the above example we are querying the “sites” table which will return a JSON response which we can parse, post-process, or even send to other systems.  First, we create a request session object and add the required Content-Type and X-API-Token headers.  The technology tables all use the method POST and require JSON data to be submitted to return a response.  How do we find this information?  It is actually very simple so let’s take a look!

Documentation

In every table you will find a “?” for the Table Description.  Clicking this button will bring up the API documentation for you.

This is where we can find the payload to post, the URL, and documentation on all the attributes.  Currently in most technology tables only columns and snapshot fields are required, all other fields are optional.  Snapshot can be one of the following:

  • An ID of a snapshot (i.e. "c8684ea9-dfd8-400d-a4b8-ba1c4bc7c185")
  • $last (latest snapshot)
  • $prev (second to latest snapshot)
  • $lastLocked (latest locked snapshot)

Filtering

Filters can also be applied to reduce the amount of data.  In the below example I created a table filter to only show Cisco devices that are matching the Red Device Uptime verification rule.

Creating the JSON filter for this is quite easy.  Once our filter is applied simply click the Table Description (“?”) icon again.  This will update the request payload with the correct syntax (see below).  This is a great way for you to learn the API and after some practice you will be able to filter without going to the webpage.  This method also works on advance filters you can create on tables as well.

1.	"filters": {
2.	    "vendor": [
3.	        "like",
4.	        "cisco"
5.	    ],
6.	    "uptime": [
7.	        "color",
8.	        "eq",
9.	        "30"
10.	    ]
11.	}

Pagination

One final note is on pagination.  Our IP Fabric demo environment with only about 600 devices contains almost 6,000 interfaces.  In a large production environment with hundreds of thousands of rows this can create slow responses or even return server errors if requesting everything at once.  Therefore, it is important to chunk your requests into smaller manageable pieces.  For this example, I have written an IPFabric class you can import into your code which will handle all the pagination for you (code has been condensed, please see the GitHub link at the end for fully documented code).

from typing import Optional, Union

from requests import Session
from urllib.parse import urljoin


class IPFabric(Session):
    def __init__(self, base_url: str, token: str, verify: bool = True, api_version: str = "v1", limit: int = 10000):
        super(IPFabric, self).__init__()
        self.base_url = urljoin(urljoin(base_url, "api/"), api_version + '/')
        self.headers.update({'Content-Type': 'application/json', 'X-API-Token': token})
        self.verify = verify
        self.limit = limit

    def query(self, endpoint: str, payload: dict):
        return self._ipf_pager(urljoin(self.base_url, endpoint), payload)

    def _ipf_pager(
            self,
            url: str,
            payload: dict,
            data: Optional[Union[list, None]] = None,
            start: int = 0
    ):
        data = list() if not data else data

        payload["pagination"] = dict(
            limit=self.limit,
            start=start
        )
        r = self.post(url, json=payload)
        r.raise_for_status()
        r = r.json()
        data.extend(r['data'])
        if self.limit + start < r["_meta"]["count"]:
            self._ipf_pager(url, payload, data, start+self.limit)
        return data

Our demonstration below will import the above class, the pager function will query the API until all rows are received, and then return a list of dictionaries which we can further process.

from ipfabric import IPFabric
from os import getenv
from pprint import pprint


if __name__ == '__main__':
    ipf = IPFabric('https://demo3.wordpress-625423-2416527.cloudwaysapps.com/', getenv('IPF_TOKEN'))

    payload = {
        "columns": [
            "sn",
            "hostname",
            "intName",
            "siteName",
            "l1",
            "l2",
            "dscr",
            "mac",
            "duplex",
            "speed",
            "errDisabled",
            "mtu",
            "primaryIp",
        ],
        "snapshot": "$last"
    }
    interfaces = ipf.query('tables/inventory/interfaces', payload)

    pprint(interfaces[0])

"""
{'dscr': None,
 'duplex': None,
 'errDisabled': None,
 'hostname': 'L62SD24',
 'intName': 'Vl1',
 'l1': 'down',
 'l2': 'down',
 'mac': 'aabb.cc82.ff00',
 'mtu': 1500,
 'primaryIp': None,
 'siteName': 'L62',
 'sn': 'a3effa6',
 'speed': None}
"""

Summary

Deploying IP Fabric in your environment and using the API can greatly speed up your network automation goals.  With support for many different vendors and platforms we remove the need for your development teams creating complex parsers and code to communicate to network devices.  On day 1 of your deployment, you can jump right to the data post processing and begin using this information in reporting, auditing, or sending to other systems.

Resources

Get IP Fabric

Request a demo and discover how to increase
your networks visibility & get better time efficiency.
Free Demo | Zero Obligation
Request a Demo
We're Hiring!
Join the Team and be part of the Future of Network Automation
Available Positions
IP Fabric, Inc.
115 BROADWAY, 5th Floor
NEW YORK NY, 10006
United States
This is a block of text. Double-click this text to edit it.
Phone : +1 (914) 752-2991
Email : [email protected]
IP Fabric s.r.o.
Kateřinská 466/40
Praha 2 - Nové Město, 120 00
Czech Republic
This is a block of text. Double-click this text to edit it.
Phone : +420 720 022 997
Email : [email protected]
IP Fabric, Inc. © 2022 All Rights Reserved