NOTE: This project is now maintained here

Timesys LinuxLink API Toolkit

This project contains a Python package and a command-line tool for
interacting with APIs for Timesys services such as
Vigiles.

Documentation generated from this repository is hosted at https://linuxlink.timesys.com/docs/api-toolkit

The server-side API endpoint documentation for Vigiles is here: https://linuxlink.timesys.com/docs/vigiles-api-manual

Install

From this repository, you can install with pip:

pip3 install .

If you want to generate the HTML docs from the source, install the extras too:

pip3 install .[docs]

Setup

Usage of the APIs requires a Key
file
for authentication. The key file contains the user's email address and
API key.

For configuring the Vigiles subpackage to use specific Product or Folder
locations, refer to the Dashboard
Config
documentation. Dashboard Config files are downloaded from Product pages
on the Vigiles Dashboard and
passed to the core LLAPI object's configure method. Product and
Folder tokens may also be set directly on that object without a file.

Most features of the API require a Vigiles Prime subscription.

Getting Started

Command Line

The python package is installed along with a script called vigiles. This script demonstrates use of the python package,
but is also useful in its own right since it exercises each method. For details on the parameters or what is returned, refer
to the Python package's documentation, or the API documentation.

To get started with the command line, try specifying a keyfile and checking the heartbeat command, which should look like this:

$ vigiles -k /path/to/linuxlink_key heartbeat
{'ok': True}

Note: If you put the Key File in the default location ($HOME/timesys/linuxlink_key), you don't need the '-k' option.

Python Package

To use the package in your own project, you must first import the LLAPI object and configure
it. Without calling timesys.llapi.configure(), no User email or API key are configured for
authentication.

>>> import timesys
>>> timesys.llapi.configure(key_file_path='/home/user/timesys/linuxlink_key')
>>>
>>> # Or, if also using a Vigiles Dashboard Config file:
>>> timesys.llapi.configure(key_file_path='/home/user/timesys/linuxlink_key', dashboard_config_path='/path/to/config')

Verify authentication and server availability:

>>> from timesys.utilities import heartbeat
>>> heartbeat()
{'ok': True}

If the heartbeat is ok, you are ready to use any of the toolkit's
modules!

Additional Notes

Logging

It is up to the user to specify any custom handlers or formats for the
logger if desired. For example:

>>> import logging
>>> import timesys
>>>
>>> my_handler = logging.StreamHandler()
>>> my_handler.setLevel(logging.INFO)
>>> formatter = logging.Formatter('%(asctime)s - %(name)s - %(levelname)s - %(message)s')
>>> my_handler.setFormatter(formatter)
>>> timesys.logger.addHandler(my_handler)

If you only want to change the log level, such as to hide warnings, you
can also configure it this way:

>>> timesys.llapi.configure(log_level='ERROR')

Authentication

If you are writing your own API client library, such as in another
language, please pay special attention to the code in
timesys.core.llapi. the
LLAPI class has private methods for generating the HMAC
auth token from the API key. If this is not done exactly the same way as
the server computes it, the signatures will never match.

To test your implementation, you can configure this module in a "dry
run" mode which will output the auth header as well as the intermediary
message used to create it (the "hmac_msg" key). Your code
should be generating the same message and using the same hashing method
to result in the same token for the header.

>>> import timesys
>>> timesys.llapi.configure(key_file_path='/path/to/linuxlink_key', dry_run=True)
Dry Run mode is enabled. No requests will be made.
>>> timesys.utilities.heartbeat()
{'headers': {'X-Auth-Signature': b'<token here>'}, 'method': 'POST', 'url': 'https://linuxlink.timesys.com/api/v1/heartbeat', 'data': {'email': 'user@example.com'}, 'hmac_msg': b'POST/api/v1/heartbeatemail=user@example.com'}