Using Argus API in commands

ArgusAPI is a package that supplies you with automatically generated endpoints for Argus. It uses Argus’s swagger.json definition to generate endpoints the first time the module is loaded, and will re-generate them again if they’re more than a day old, ensuring that the local functions are up to date with the remote API.

When Argus API has converted the api definition into Python code, the modules will be available under the module argus_api.api and can be imported like any other Python module — you only need to import the functions you actually need.

Using Argus API in your scripts

By default, all API functions accept some additional arguments apart from their normal API parameters, provided by this package. These are:

Argument	Default	Description
`json`	`True`	Return the JSON as a dict. If this is set to `False`, a `requests.Response` object will be returned.
`apiKey`	`None`	Explicitly provide an API key to use for authenticating the request.
`verify`	`True`	Set this to `False` to disable SSL/TLS verification, or provide a path to a TLS/SSL certificate to verify against. Caution This is not recommended to set to `False`. You should set a cert in your environment instead.
`authentication`	`{}`	Extra authentication headers. You may pass in either a `dict` of headers to add to the request, or a function that returns a dict of headers. The function will receive the target URL of the request.

Simply import the functions you want to use, and begin using them, e.g:

from argus_api.api.alarms.v1.alarm import get_alarms

def your_function(authentication: callable):
    """Do something with the API"""
    alarms = get_alarms()

Authentication

ArgusAPI supports authentication with a variety of methods. When using the ^ library, you can always pass apiKey="YOUR API KEY" to any function that interacts with the API, or you can decorate your function with the provided authentication helper argus_api.helpers.authentication.with_authentication, and receive a keyword argument authentication that you can pass to any function you import. This will ensure your API calls are authenticated.

This package provides a couple of different helpers to help you authenticate your requests, abstracting away the need to ask the user for API keys or username / password.

Option 0: Do nothing

By default, argus_api will fetch your API-key from argus_cli. Thus you just have to call the API function, and it will do the magic for you.

Option 1: Provide an API key

All API functions accept the apiKey keyword argument, so passing an API key to the function will always be supported.

from argus_api.api.alarms.v1.alarm import get_alarms, search_alarms
from argus_cli.settings import settings

def your_function():
    """Do something with the API"""

    # Just pass on the authentication variable to your API calls, and
    # they'll be authenticated
    alarms = get_alarms(apiKey=settings["api"]["api_key"])

Option 2: Using a decorator

The with_authentication decorator creates a function that helps you generate a valid authentication headers for Argus.

In the case of API key, it will just return the correct headers with your API key to Argus, while if you use LDAP / TOTP / Password authentication, it will generate the CSRF token based on your session key after logging you into Argus. This function is passed to the decorated method as a keyword argument called authentication, and can be passed along to any generated API function.

from argus_api.api.alarms.v1.alarm import get_alarms, search_alarms
from api_generator.helpers import authentication

@authentication.with_authentication(mode="api_key", api_key=os.environ.get("ARGUS_API_KEY))
def your_function(authentication: callable):
    """Do something with the API"""

    # Just pass on the authentication variable to your API calls, and
    # they'll be authenticated
    alarms = get_alarms(authentication=authentication)

Option 3: Turn a function into an authenticated function

from argus_api.api.alarms.v1.alarm import get_alarms, search_alarms
from api_generator.helpers import authentication

# Wrap the function with_credentials and set the mode to "password"
# Since no username / password are provided, Argus API will ask the user for this.
get_authenticated_alarms = authentication.with_credentials(mode="password")(get_alarms)

# Provide an API key:
search_authenticated_alarms = authentication.with_api_key(api_key=os.environ.get("ARGUS_API_KEY"))(search_alarms)

def your_function():
    """Do something with the API"""

    # Just pass on the authentication variable to your API calls, and
    # they'll be authenticated
    alarms = get_authenticated_alarms()

    search = search_authenticate_alarms(keywords=["This call uses my API key!"])