ciscodevnet / uniq

A Python API client library for Cisco's Application Policy Infrastructure Controller Enterprise Module (APIC-EM) Northbound APIs.

uniq is a Python API client library for Cisco's Application Policy Infrastructure Controller Enterprise Module (APIC-EM) Northbound APIs.

Description

The APIC-EM Northbound Interface is the only API that you will need to control your network programmatically. The API is function rich and provides you with an easy-to-use, programmatic control of your network elements, interfaces, and hosts.

The APIC-EM API provides you with the ability to think about your network at a higher policy level rather than how to implement that policy. When you use the APIC-EM API, your applications will make network policy decisions, which will then be implemented by the APIC-EM Controller through its Southbound Interfaces. Thus you tell the network what you want (i.e., the policy) and the controller figures out how to implement that policy for you.

The APIC-EM API is REST based and thus you will discover and control your network using HTTP protocol with HTTP verbs (i.e., GET, POST, PUT, and DELETE) with JSON syntax.

This package provides a handle to this rich API library in an easy to consume fashion.

Getting Started

Install

To install uniq, simply

pip install uniq

Use

Import the package and make an API call.

from uniq.apis.nb.client_manager import NbClientManager

client = NbClientManager(
    server="1.1.1.1",
    username="username",
    password="password",
    connect=True)

# NorthBound API call to get all users
user_list_result = client.user.getUsers()

# Serialize the model object to a python dictionary
users = client.serialize(user_list_result)

print(users)

Running Tests

The tests are located in the tests directory. After installing the package, they can be run by executing the below command:

python setup.py test

Sample Scripts

For sample scripts check out the sample_scripts directory.

Python

This project has been tested and working on Python 3.0+

uniq's Issues

How to set a discovery to active

Hi

I am trying to figure out how to use the DiscoveryAPI. The code I have put together is below, but it is not quite working.

I am getting " Bad Request for url: https://192.168.1.13/api/v1/discovery" when calling the client.discovery.updateDiscovery() function.

What should I be doing here please?

Many thanks

Nathan

import requests.exceptions

from uniq.apis.nb.client_manager import NbClientManager
from uniq.apis.nb.clients.inventory_manager_client.models.DiscoveryNIO import DiscoveryNIO


try:
  client = NbClientManager(
                server="192.168.1.13",
                username="admin",
                password="xxxxxx!",
                connect=True)

except requests.exceptions.HTTPError as exc_info:
  print(exc_info)
  exit(1)

discoveryNIO = DiscoveryNIO()
discoveryNIO.discoveryStatus = "active"

try:
  client.discovery.updateDiscovery(discovery = discoveryNIO, scope = "All")
except requests.exceptions.HTTPError as exc_info:
  print(exc_info)
  exit(1)

exit(0)

Which version of Python is required?

Hi

The attached image shows what happens when I try uniq with Python 2.7, which did not work.

I tried Python3 also, but that would not install.

Apologies, but I am at a bit of a loss here.

I am using Linux 4.4.0-21-generic, which is an Ubuntu 16.04 distribution.

Regards

Nathan

should be able to search file namespace by id too

https://{{apic}}:{{port}}/api/v1/file/namespace/config?id=3085587b-d226-4abd-8509-3b7756285165
{
"response": [
{
"nameSpace": "config",
"name": "2960-client.txt",
"downloadPath": "/file/3085587b-d226-4abd-8509-3b7756285165",
"fileSize": "512",
"fileFormat": "text/plain",
"md5Checksum": "c905b02d675babf2f954ba485cc244f1",
"sha1Checksum": "f72b936d02c0eece173179da516c78dfd3045f2f",
"id": "3085587b-d226-4abd-8509-3b7756285165"
}
],
"version": "1.0"
}

Same as earlier issue sort by name

No 'description' information

No 'description' value information when pull interface information.

support for the 1.4 command-runner API

It is possible to add support for this new API?

thanks for resolving the other issues so quickly

pip install uniq not working

Hi

The attached image shows what happens when I try to install uniq via pip.

Did you mean to literally just use pip, or were you expecting the repository to have been cloned first? In, any case, I tried cloning too, and that didn't seem to work.

What did work was:

sudo python setup.py install

Thanks

Nathan

parameterized file search is not available

The APIC-EM UI allows a parameterised search for a file
https://{{apic}}:{{port}}/api/v1/file/namespace/config?name=2960-config.txt
returns
{
"response": [
{
"nameSpace": "config",
"name": "2960-client.txt",
"downloadPath": "/file/3085587b-d226-4abd-8509-3b7756285165",
"fileSize": "512",
"fileFormat": "text/plain",
"md5Checksum": "c905b02d675babf2f954ba485cc244f1",
"sha1Checksum": "f72b936d02c0eece173179da516c78dfd3045f2f",
"id": "3085587b-d226-4abd-8509-3b7756285165"
}
],
"version": "1.0"
}

this does not seem to be available via uniq?

Traceback (most recent call last):
File "./create_and_upload.py", line 94, in
create_and_upload(apic, devices=DEVICES, template_file=TEMPLATE)
File "./create_and_upload.py", line 83, in create_and_upload
file_id = upload_file(apic, config_filename, outputText)
File "./create_and_upload.py", line 45, in upload_file
file_present = apic.file.getFilesByNamespace(nameSpace="config", name="2960-client.txt")
File "/Users/aradford1/Documents/work/PycharmProjects/uniq-examples/env/lib/python3.4/site-packages/uniq-1.2.0-py3.4.egg/uniq/apis/nb/clients/api_client.py", line 124, in wrapper
return list(version_function_map.values())[0](*args, **kwargs)
File "/Users/aradford1/Documents/work/PycharmProjects/uniq-examples/env/lib/python3.4/site-packages/uniq-1.2.0-py3.4.egg/uniq/apis/nb/clients/file_service_client/FileApi.py", line 188, in getFilesByNamespace
raise TypeError("Got an unexpected keyword argument '%s' to method getFilesByNamespace" % key)
TypeError: Got an unexpected keyword argument 'name' to method getFilesByNamespace

I added the parameter to getFilesByNamespace() (on my machine)

    allParams = ['nameSpace', 'scope', 'name']
    #allParams = ['nameSpace', 'scope']

and it now works.

Documentation for api endpoints and their corresponding API calls

Currently, there is no way to know which method call would invoke a certain API endpoint.
A doc link which displays that would be helpful.

No API for license

The license API in inventory do not appear here?

Inventory

license : license API Show/Hide List Operations Expand Operations Raw
GET /license-info/network-device/{deviceId} Retrieves the license info for a network devices by filters
GET /license-info/network-device/{deviceId}/count Retrieves the license info for a network devices by filters
GET /network-device/license/{licenseFileName} Retrieves the list of devices with given license filenames

pip install broken for Centos7

in setup.py the directive shows this...

package_dir={'uniq': ''},

should be this...

package_dir={'uniq': '.'},

This is breaking pip installs for me.

Centos 7.1 64bit
Software collections - python33
(venv2)[vagrant@localhost uniq]$ pip list
argparse (1.4.0)
cffi (1.9.1)
cryptography (1.7.1)
enum34 (1.1.6)
idna (2.2)
ipaddress (1.0.18)
lxml (3.7.2)
ncclient (0.5.3)
netaddr (0.7.19)
paramiko (2.1.1)
pip (1.4.1)
pyang (1.7.1)
pyasn1 (0.1.9)
pycparser (2.17)
requests (2.12.5)
setuptools (0.9.8)
six (1.10.0)
wheel (0.29.0)

See this for more info...

http://stackoverflow.com/questions/27408938/cant-copy-anifest-in-doesnt-exist-or-not-a-regular-file

Unable to handle an exception

I am getting this error and I unable to handle the exception, even if I put the operation under try and except.

Error:

Error Code: 404 URL:https://sandboxapic.cisco.com/api/v1/interface/network-device/17184480-2617-42c3-b267-4fade5f794a9 Data:{} Headers:{'X-Auth-Token': 'ST-4896-fVSZ1kDWAu0aKwnJtfcb-cas', 'Cookie': 'JSESSIONID=4DFF3F3BAC4B9E8C1F4F1B026DE4821F; Path=/apic-em-inventory-manager-service/; HttpOnly; Secure', 'Content-Type': 'application/json', 'Accept': 'application/json', 'X-CSRF-Token': 'soon-enabled'} Message:{"response":{"errorCode":"Not found","message":"Request data not found","detail":"No resource found with deviceId: 17184480-2617-42c3-b267-4fade5f794a9"},"version":"1.0"}
Traceback (most recent call last):
  File "C:\Python35-32\lib\site-packages\uniq\apis\client_manager.py", line 187, in call_api
    response.raise_for_status()
  File "C:\Python35-32\lib\site-packages\requests\models.py", line 862, in raise_for_status
    raise HTTPError(http_error_msg, response=self)
requests.exceptions.HTTPError: 404 Client Error: Not Found for url: https://sandboxapic.cisco.com/api/v1/interface/network-device/17184480-2617-42c3-b267-4fade5f794a9

Code:

from uniq.apis.nb.client_manager import NbClientManager

apicEmServer = NbClientManager(server="sandboxapic.cisco.com",
                                 username="devnetuser",
                                 password="Cisco123!",
                                 connect=True)

allNetworkDevices = []
allInterfaces = {}
try:
    allNetworkDevices = apicEmServer.networkdevice.getAllNetworkDevice()
    allNetworkDevices = apicEmServer.serialize(allNetworkDevices)
except:
    print("Error") 
if allNetworkDevices is not None:
    for networkDevice in range(len(allNetworkDevices['response'])):

        try:
            deviceInterfaces = apicEmServer.interface.getInterfaceByDeviceId(deviceId = allNetworkDevices['response'][networkDevice]['id'])
            deviceInterfaces = apicEmServer.serialize(deviceInterfaces)
            print(allNetworkDevices['response'][networkDevice]['id'])

            if deviceInterfaces is not None:
                for line in range(len(deviceInterfaces['response'])):
                    if deviceInterfaces['response'][line]['description'] != "" and deviceInterfaces['response'][line]['description'] is not None:
                        allInterfaces[deviceInterfaces['response'][line]['description']] = allNetworkDevices['response'][networkDevice]['hostname'], allNetworkDevices['response'][networkDevice]['managementIpAddress'], deviceInterfaces['response'][line]['portName']
        except:
            print("Unable to get interface information from " + allNetworkDevices['response'][networkDevice]['id'])
print(allInterfaces)`

deletePnpSiteByID does not have true/false for parameters.

The correct call is:
deletePnpSiteByID(projectId=project_id, deleteRule=1, deleteDevice=1)

the documentation in https://github.com/CiscoDevNet/uniq/blob/master/apis/nb/clients/network_plug_and_play_client/PnpprojectApi.py
says otherwise
deleteRule, int: Delete project rules (true) or not (false) (required)
deleteDevice, int: Delete project devices (true) or not (false) (required)

Add support for Python v2 compatibility

For API reference libraries like this, to aid in adoption, it is very helpful if the package can be written to provide compatibility for both Python v2 and v3.

Having just gone through this process (taking a v2 package that I authored, and adding support for v3) sometimes the needed changes are trivial and sometimes they are easy. Based only on a quick look at the package's code and dependencies, this may not be to intensive of an update if leveraging some of the tools and packages that have been created to assist with efforts like these.

conversion assistance script...
pasteurize: Py3 to Py2/3

Packages:

• future
• six

scope=all in the discovery sample is incorrect for APIC-EM 1.3

Hi

The argument scope=all in the add_discovery_job.py is incorrect in a few places.

You need to remove it.

Regards

Nathan

Issue running py.test

I tried to run py.test on the tests directory. I got an error message
py.test
=========================================== test session starts ===========================================
platform darwin -- Python 2.7.10 -- py-1.4.31 -- pytest-2.7.1
rootdir: /Users/aradford1/Documents/work/PycharmProjects/uniq-examples/uniq, inifile:
collected 0 items / 2 errors

================================================= ERRORS ==================================================
___________________ ERROR collecting build/lib/uniq/tests/nb/test_nb_client_manager.py ____________________
build/lib/uniq/tests/nb/test_nb_client_manager.py:1: in
from unittest.mock import MagicMock
E ImportError: No module named mock

I changed the first line to
from mock import MagicMock

how to upload a file inline?

Normally if I am creating a file dynamically, i do an inline upload.
files = {'fileUpload': (filename, filebody)}
do_post("file-service/file/config", files=files)

I could not see how to do this with apic.file.uploadFile ?

I might be missing something obvious?

tried to pull an updated version and re-install and hit an error.

I ended up
rm -rf build dist
then python setup.py install

and it was fine.

Here is the first error if I just do a git pull, then a python setup.py install
byte-compiling build/bdist.macosx-10.6-intel/egg/uniq/apis/nb/services/task/init.py to init.cpython-34.pyc
byte-compiling build/bdist.macosx-10.6-intel/egg/uniq/apis/nb/services/task/task.py to task.cpython-34.pyc
byte-compiling build/bdist.macosx-10.6-intel/egg/uniq/tests/nb/test_nb_client_manager.py to test_nb_client_manager.cpython-34.pyc
byte-compiling build/bdist.macosx-10.6-intel/egg/uniq/utils/init.py to init.cpython-34.pyc
byte-compiling build/bdist.macosx-10.6-intel/egg/uniq/utils/wait.py to wait.cpython-34.pyc
creating build/bdist.macosx-10.6-intel/egg/EGG-INFO
copying uniq.egg-info/PKG-INFO -> build/bdist.macosx-10.6-intel/egg/EGG-INFO
copying uniq.egg-info/SOURCES.txt -> build/bdist.macosx-10.6-intel/egg/EGG-INFO
copying uniq.egg-info/dependency_links.txt -> build/bdist.macosx-10.6-intel/egg/EGG-INFO
copying uniq.egg-info/requires.txt -> build/bdist.macosx-10.6-intel/egg/EGG-INFO
copying uniq.egg-info/top_level.txt -> build/bdist.macosx-10.6-intel/egg/EGG-INFO
zip_safe flag not set; analyzing archive contents...
uniq.apis.nb.pycache.client_manager.cpython-34: module references file
uniq.apis.nb.clients.file_service_client.pycache.init.cpython-34: module references file
uniq.apis.nb.clients.file_service_client.models.pycache.init.cpython-34: module references file
uniq.apis.nb.clients.identity_manager_client.pycache.init.cpython-34: module references file
uniq.apis.nb.clients.identity_manager_client.models.pycache.init.cpython-34: module references file
uniq.apis.nb.clients.inventory_manager_client.pycache.init.cpython-34: module references file
uniq.apis.nb.clients.inventory_manager_client.models.pycache.init.cpython-34: module references file
uniq.apis.nb.clients.ipgeo_client.pycache.init.cpython-34: module references file
uniq.apis.nb.clients.ipgeo_client.models.pycache.init.cpython-34: module references file
uniq.apis.nb.clients.ippool_client.pycache.init.cpython-34: module references file
uniq.apis.nb.clients.ippool_client.models.pycache.init.cpython-34: module references file
uniq.apis.nb.clients.network_discovery_client.pycache.init.cpython-34: module references file
uniq.apis.nb.clients.network_discovery_client.models.pycache.init.cpython-34: module references file
uniq.apis.nb.clients.network_plug_and_play_client.pycache.init.cpython-34: module references file
uniq.apis.nb.clients.network_plug_and_play_client.models.pycache.init.cpython-34: module references file
uniq.apis.nb.clients.pki_broker_service_client.pycache.init.cpython-34: module references file
uniq.apis.nb.clients.pki_broker_service_client.models.pycache.init.cpython-34: module references file
uniq.apis.nb.clients.policy_analysis_client.pycache.init.cpython-34: module references file
uniq.apis.nb.clients.policy_analysis_client.models.pycache.init.cpython-34: module references file
uniq.apis.nb.clients.policy_manager_client.pycache.init.cpython-34: module references file
uniq.apis.nb.clients.policy_manager_client.models.pycache.init.cpython-34: module references file
uniq.apis.nb.clients.rbac_service_client.pycache.init.cpython-34: module references file
uniq.apis.nb.clients.rbac_service_client.models.pycache.init.cpython-34: module references file
uniq.apis.nb.clients.scheduler_service_client.pycache.init.cpython-34: module references file
uniq.apis.nb.clients.scheduler_service_client.models.pycache.init.cpython-34: module references file
uniq.apis.nb.clients.task_service_client.pycache.init.cpython-34: module references file
uniq.apis.nb.clients.task_service_client.models.pycache.init.cpython-34: module references file
uniq.apis.nb.clients.topology_client.pycache.init.cpython-34: module references file
uniq.apis.nb.clients.topology_client.models.pycache.init.cpython-34: module references file
Traceback (most recent call last):
File "setup.py", line 64, in
author_email='[email protected], [email protected]',
File "/Library/Frameworks/Python.framework/Versions/3.4/lib/python3.4/distutils/core.py", line 148, in setup
dist.run_commands()
File "/Library/Frameworks/Python.framework/Versions/3.4/lib/python3.4/distutils/dist.py", line 955, in run_commands
self.run_command(cmd)
File "/Library/Frameworks/Python.framework/Versions/3.4/lib/python3.4/distutils/dist.py", line 974, in run_command
cmd_obj.run()
File "/Users/aradford1/Documents/work/PycharmProjects/uniq-examples/env/lib/python3.4/site-packages/setuptools/command/install.py", line 67, in run
self.do_egg_install()
File "/Users/aradford1/Documents/work/PycharmProjects/uniq-examples/env/lib/python3.4/site-packages/setuptools/command/install.py", line 109, in do_egg_install
self.run_command('bdist_egg')
File "/Library/Frameworks/Python.framework/Versions/3.4/lib/python3.4/distutils/cmd.py", line 313, in run_command
self.distribution.run_command(command)
File "/Library/Frameworks/Python.framework/Versions/3.4/lib/python3.4/distutils/dist.py", line 974, in run_command
cmd_obj.run()
File "/Users/aradford1/Documents/work/PycharmProjects/uniq-examples/env/lib/python3.4/site-packages/setuptools/command/bdist_egg.py", line 209, in run
os.path.join(archive_root, 'EGG-INFO'), self.zip_safe()
File "/Users/aradford1/Documents/work/PycharmProjects/uniq-examples/env/lib/python3.4/site-packages/setuptools/command/bdist_egg.py", line 245, in zip_safe
return analyze_egg(self.bdist_dir, self.stubs)
File "/Users/aradford1/Documents/work/PycharmProjects/uniq-examples/env/lib/python3.4/site-packages/setuptools/command/bdist_egg.py", line 355, in analyze_egg
safe = scan_module(egg_dir, base, name, stubs) and safe
File "/Users/aradford1/Documents/work/PycharmProjects/uniq-examples/env/lib/python3.4/site-packages/setuptools/command/bdist_egg.py", line 392, in scan_module
code = marshal.load(f)
ValueError: bad marshal data (unknown type code)

Getting more than 500 lines

Hi,

The maximum number of entries returned by a GET API is 500 (default), I know there is a way to pull more information using /{start}/{end} or using offset={offset} but Is there a way to do this with UNIQ library?

Thanks in advance,
Arik

see problem to log in to testACI machine

i have an instance on ACI in a lab and i tested the code to log in, but with the actual
apy/nb/client_manager.py i am unable to authenticate

# resource_path = "/ticket" resource_path = "/aaaLogin.json" user_info = { "aaaUser": { "attributes": { "name": self.username, "pwd": self.password } } } # data = json.dumps({"username": self.username, "password": self.password}) data = json.dumps(user_info)

the commented part is the original part. i replaced the path to the aaaLogin.json that will return me the response and the token that i can thake from the response in this way

result_json = response.json()
response.json()['imdata'][0]['aaaLogin']['attributes']['token']

daily backup script has disappeared?

Was the daily backup script removed?

License API seem to have dropped out again.

Ths .json file is present, but no .py

connectedDeviceIp changed to connectedNetworkDeviceIpAddress

Hi,
I installed APIC-EM version 1.3 and it looks like the value connectedDeviceIp was changed to connectedNetworkDeviceIpAddress in get hosts method. Is there any update to Uniq library in the near future?

file/downLoadFile does not return anything?

there is no return statement for downLoadFile

PnP API are missing?

Is there a plan to add the PnP api as well?

[Sorry, i needed to look more carefully ]

DRY versions of __wait_for_task_failure and __wait_for_task_success

It looks like these could be refactored using __wait_for_task_complete, then look at the status?
Do there need to be 3 versions of essentially the same code?