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:

.. csv-table::
   :header: "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:

.. code-block:: python

    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.

.. code-block:: python

    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.

.. code-block:: python

    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
""""""""""""""""""""""""""""""""""""""""""""""""""""""""

.. code-block:: python

    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!"])