argus-api#

The argus-api library provides a collection of methods interacting with Argus APIs.

Installation#

Install argus-api using pip:

pip install argus-api

Usage#

argus_api.api vs argus_api.lib#

The argus_api contains two main modules : argus_api.api and argus_api.lib.

Both modules have the same content, ` but argus_api.api` is present for mostly historical reasons and should never be used, unless writing an argus-cli module. For all other use cases, always use argus_api.lib.

importing methods#

Every Argus API endpoint has a corresponding argus-api function, which will returns the deserialized JSON body of the response.

Submodules in the packages are organised as argus_api.[api|lib].[service].[version].[resource].

Each submodules contains the functions for querying relevant endpoints.

For instance, the function retrieving the current user can be imported using :

from argus_api.lib.currentuser.v1.user import get_current_user

for a complete list of available functions, see API functions reference

API session#

API requests are sent by a session object (ArgusAPISession), which handles configuration and authentication. In order to construct an API session, first create an authentication object using one of the supported authentication methods:

# API key authentication:
from argus_api.authentication import APIKeyAuth
auth = APIKeyAuth(api_key="my_api_key")
# OR password authentication:
from argus_api.authentication import PasswordAuthentication
auth = PasswordAuthentication(username="my_username", password="my_password")
# OR LDAP authentication:
from argus_api.authentication import PasswordAuthentication
auth = LDAPAuthentication(username="my_username", password="my_password")

Then construct a session object:

from argus_api.session import ArgusAPISession

session = ArgusAPISession(auth=auth)

That session object can then be passed to argus_api functions using the api_session argument:

from argus_api.lib.currentuser.v1.user import get_current_user

get_current_user(api_session=session)

Note

if a string is passed as the auth argument to ArgusAPISession, it will be interpreted as an API key.

so this:

from argus_api.authentication import APIKeyAuth

session = ArgusAPISession(auth="my_api_key")

is equivalent to this:

from argus_api.authentication import APIKeyAuth

auth = APIKeyAuth(api_key="my_api_key")
session = ArgusAPISession(auth=auth)

Global session#

if no session object is passed to argus_api functions, a global session will be used by default. The global session is unauthenticated by default, but can be retrieved and modified using the argus_api.session.get_session() and argus_api.session.set_session() functions.

To authenticate the global session:

from argus_api.session import get_session
from argus_api.authentication import APIKeyAuth
from argus_api.lib.currentuser.v1.user import get_current_user

auth = APIKeyAuth(api_key="my_api_key")

global_session = get_session()
global_session.auth = auth

# following API requests will be authenticated
get_current_user()

To replace the global session:

from argus_api.session import set_session
from argus_api.authentication import APIKeyAuth
from argus_api.lib.currentuser.v1.user import get_current_user

session = ArgusAPISession(auth=APIKeyAuth(api_key="my_api_key"))

set_session(session)

# following API requests will be authenticated
get_current_user()

Lastly, a session object can be used as a context manager. When used that way, it will override the global session inside the with block:

from argus_api.session import set_session
from argus_api.authentication import PasswordAuthentication
from argus_api.lib.currentuser.v1.user import get_current_user

session_user_1 = ArgusAPISession(auth=PasswordAuthentication(username="user_1", password="..."))
session_user_2 = ArgusAPISession(auth=PasswordAuthentication(username="user_2", password="..."))

with session_user_1:
    # following API requests will be authenticated as user_1
    get_current_user()
with session_user_2:
   # following API requests will be authenticated as user_2
    get_current_user()
# following requests will use the default global session

Explicit session authentication#

By default, session authentication will take place when the the session object sends its first request.

It is however possible to explicitly pre-authenticate the session by calling its authenticate() method:

session = ArgusAPISession(auth=PasswordAuthentication(username="user", password="..."))
session.authenticate()

If authentication fails, it will raise an ArgusAPIAuthenticationError exception.

Some authentication methods (for instance API key authentication) do not need to perform a login and will not fail before sending a first request. It is possible to request the credentials to always be validated on authentication by setting the check argument to True :

from argus_api.exceptions.client import ArgusAPIAuthenticationError
from argus_api.exceptions.http import AuthenticationFailedException
from argus_api.lib.currentuser.v1.user import get_current_user

# default behavior
session1 = ArgusAPISession(auth=APIKeyAuth("invalid_key"))
try:
    session1.authenticate()
except argus_api.exceptions.client.ArgusAPIAuthenticationError
   # this exception will NOT be raised, as no request has been sent
   ...
try:
    get_current_user(api_session=session1)
except AuthenticationFailedException:
    # the request will fail due to the invalid API key
    print("authentication failed on request")

# using check=True
session2 = ArgusAPISession(auth=APIKeyAuth("invalid_key"))
try:
    session1.authenticate(check=True)
except argus_api.exceptions.client.ArgusAPIAuthenticationError
   # this exception will NOT be raised, as no request has been sent
   print("authentication failed check")

If using the session object’s authenticate() method to verify user credentials, always use check=True.

Creating constrained sessions#

A constrained session (a session restricted to a subset of customers and/or functions) can be created from an existing session using the new_constrained_session() method:

from argus_api.session import ArgusAPISession
from argus_api.authentication import APIKeyAuth

auth = APIKeyAuth(api_key="my_api_key")
original_session = ArgusAPISession(auth=auth)

constrained_session = original_session.new_constrained_session(customers=["customer1"], functions=["viewCases", "viewCases"])

In this example, original_session will have access to all customers and functions my_api_key has access to, while constrained_session will have be limited to the viewCases and viewCases function for customer1.

Session configuration#

In addition to authentication, a session object can be used to configure different aspects of the connection to the Argus API.

In the following examples, session is an instance of argus_api.session.ArgusAPISession.

proxy configuration#

Outgoing proxies can be set at the session level by setting the proxies property on the session object :

session.proxies = {"http": "http://proxy.corp.com:8080", "https": "http://proxy.corp.com:8080"}

Note that argus_api will also honor the HTTP_PROXY, HTTPS_PROXY and NO_PROXY environment variables.

SSL certificate validation#

By default, SSL certification is performed against requests’s bundled root CA certificates bundle. It is possible to change that behavior by setting the verify property on the session object :

session.verify = "/path/to/ca_bundle.crt"

The value can be True (default behavior), False (disable certificate validation, not recommended) or a string containing to the location of a CA bundle.

Note that argus_api will also honor the REQUESTS_CA_BUNDLE environment variable.

client-side timeout#

In order to prevent hanging on abnormally long delays, requests issued by argus_api will timeout after 30 seconds by default.

It is possible to change that value by calling the set_timeout() method and passing it the desired timeout value in seconds :

session.set_timeout(60)

Alternatively, the ARGUS_API_TIMEOUT environment variable can be set to the desired value. If that environment variable is set and set_timeout() is used, the value used with set_timeout() will take precedence.

Warning

set_timeout() will reset any changes made with set_adapter() - if you need to specify both retry options and timeout, use set_adapter() instead.

retry strategy#

argus_api will automatically retry some failed requests before raising an exception.

The default retry strategy is to retry maximum 3 times on network errors and status codes 500, 503 and 504.

These settings as well as the timeout delay can be changed using the set_adapter() method :

session.set_adapter(default_timeout=60, max_retries=10)

common function arguments#

On top of the parameters relevant to each endpoint, every function provided by argus-api accepts the following arguments :

  • api_session: the session object used to construct and send the request

  • apiKey: API key to authenticate the requests with. If used, it will take precedence over the api_session argument.

  • verify: controls how certificate validation is performed - this is passed directly to the verify parameter of requests.request().

  • proxies : proxy configuration - passed directly to the proxies argument of requests.request()

  • authentication : allows overriding api-key based authentication. This argument can be set to a headers dictionary, an authentication object or a callable that takes the request URL as its only arguments and returns a headers dictionary.

  • server_url : allows overriding the API base URL - mostly useful for development. note that the URL should be provided without a trailing /.

  • headers: allows specifying arbitrary headers as a dict

  • json : some API endpoints accept multiple content type, including JSON. This argument, which defaults to True, controls whether the parameters should be sent as JSON for such endpoints.

  • body : allows specifying arbitrary fields in the request body.

schemas#

The argus-api package is generated from the swagger specification for Argus APIs.

The specifications used for generation can be retrieved in two different ways :

  • the entire schema for each service is bundled as an importlib resources and can be imported from argus_api.schema.<service_name>.schema, for example from argus_api.schema.cases import schema. schema will be a pathlib.Path object pointing to the location of the swagger specification on disk.

  • the swagger path definition for an endpoint can be retrieved by replacing lib or api in the import path with schema, for example from argus_api.schema.currentuser.v1.user import get_current_user.