Skip to content

Use Python for API requests

Zenoss recommends using the zenApiLib library to interact with Collection Zone and Resource Manager instances. You can also use the Python requests library.

zenApiLib

The zenApiLib library provides the following benefits:

  • employs the Python logging library
  • provides paging API support by using the limit parameter of router methods to break large results into manageable chunks
  • API result error checking
    • Content-Type JSON, return decoded JSON object
    • Content-Type HTML, return error with HTML page title
  • API call error checking
    • Validate specified router exists
    • Validate called method exists
  • provides backward compatibility with zenoss_api.ZenAPIConnector.ZenAPIConnector
  • supports multiple Zenoss instance definitions in a single credential file
    • credential file name defaults to creds.cfg and the same directory as the zenApiLib.py file
    • ability to specify credential file
  • includes the zenApiCli.py script for simple command line API interaction, which can be easily incorporated into existing shell scripts

The zenApiLib library is not officially supported.

API router helper libraries

Files: zenApiDeviceRouterHelper.py, zenApiImpactRouterHelper.py

Router-specific helper libraries contain common, repeatedly-used functionality.

Installing zenApiLib

Prerequisites

ZenApiLib depends on the following Python libraries: requests, pyOpenSSL, ndg-httpsclient, pyasn1

You can install those quickly with pip:

yum -y install python-pip
pip install requests pyOpenSSL ndg-httpsclient pyasn1

Installation

To install zenApiLib, download the master branch directly from the github page and unzip it.

wget https://github.com/zenoss/zenoss-RM-api/archive/master.zip -O zenApiLib.zip
unzip zenApiLib.zip

Environment

If your script(s) are not in the same directory as zenApiLib.py or the standard python lib directories, then update your $PYTHONPATH environment variable to include that directory.

cd path-to-directory-containing-zenApiLib.py
export PYTHONPATH=$PYTHONPATH:$(pwd)

The credentials creds.cfg file by default is expected to be in the same directory as zenApiLib.py. A different location can be specified at instantiation.

zenApiLib command-line usage

Usage:

$ ./zenApiCli.py --help 
usage: zenApiCli.py [-h] [-v LOGLEVEL] [-t TIMEOUT] -r routerName -m routerMethodName 
                    [-c credsSection] [-p credsFilePath] [-d KEY1=VAL1,KEY2=VAL2...] 
                    [-x fieldName.fieldName...]

      Command Line Interface to Zennos JSON API, can be used to make simple API calls.

optional arguments:
  -h, --help            show this help message and exit
  -v LOGLEVEL           Set script logging level (DEBUG=10, INFO=20, WARN=30,
                        *ERROR=40, CRTITICAL=50
  -t TIMEOUT            Override API call creds file timeout setting
  -r routerName         API router name
  -m routerMethodName   API router method to use
  -c credsSection       zenApiLib credential configuration section (default)
  -p credsFilePath      Default location being the same directory as the
                        zenApiLib.pyfile
  -d KEY1=VAL1,KEY2=VAL2...
                        Parameters to pass to router's method function
  -x fieldName.fieldName...
                        Return value from API result field. Default:
                        'result.success'. Special keyword 'all' to dump API
                        results.

Examples

Send an event

./zenApiCli.py -r EventsRouter -m add_event \
  -d summary="this is a test",component="test" \
  -d device="Null" -d severity=4,evclass="/Status" -d evclasskey="sma"

Get device's productionState value

./zenApiCli.py -r DeviceRouter -m getDevices \
  -d uid="/zport/dmd/Devices/ControlCenter" \
  -d params="{'ipAddress': '10.88.111.223'}" \
  -x result.devices.0.productionState

Get all devices in a deviceClass and their statuses

./zenApiCli.py -r DeviceRouter -m getDevices \
  -d uid="/zport/dmd/Devices",keys='["name","status"]' \
  -x result.devices.*.name -x result.devices.*.status

zenApiLib in Python scripts

The zenApiLib library contains some key classes, namely zenConnector, that can be used in Python.

Instantiating zenConnector

The zenApiLib library must be imported. In this example, we create a local instance of the zenConnector class called api:

import zenApiLib
api = zenApiLib.zenConnector()

Specifying a router

Once we have a zenConnector instance, we need to choose a router. In this example, we've chosen TriggersRouter:

api.setRouter('TriggersRouter')

When setRouter is used, an API call is made to our Collection Zone or Resource Manager instance to ensure that the router being invoked exists. If it does not, an exception will be raised.

Calling a method

After we've specified the router we want to use, we can start executing methods provided by that router. In this example, we invoke the getTriggers method:

api.callMethod('getTriggers')

When callMethod is used, if the call was successful, it returns the results as a Python dictionary.

More examples

For more examples, refer to the examples directory in the zenApiLib repository.