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 theapi_session
argument.
verify
: controls how certificate validation is performed - this is passed directly to theverify
parameter ofrequests.request()
.
proxies
: proxy configuration - passed directly to theproxies
argument ofrequests.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 fromargus_api.schema.<service_name>.schema
, for examplefrom 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 replacinglib
orapi
in the import path withschema
, for examplefrom argus_api.schema.currentuser.v1.user import get_current_user
.