Connecting

To use the Squonk2 Data Manager or Account Server API you will need a user access token.

If you do not have a token the method Auth.get_access_token() will return one from an appropriate keycloak instance and user credentials. Every API method will need an access token.

In this example we use the Python argparse module to extract sensitive keycloak material form the command line and the os.environ module to get a username and password from a pair of environment variables.

import argparse
import os

from squonk2.auth import Auth

# Username and password are taken from environment variables...
keycloak_user: str = os.environ['DMAPI_USERNAME']
keycloak_user_password: str = os.environ['DMAPI_USERNAME_PASSWORD']

# Less sensitive information is extracted from the command-line...
parser = argparse.ArgumentParser(description='Delete All DM Project Instances')
parser.add_argument('--keycloak-hostname', '-k',
                    help='The API URL, i.e. "example.com"',
                    required=True)
parser.add_argument('--keycloak-realm', '-r',
                    help='The Keycloak realm, i.e. "blob"',
                    required=True)
parser.add_argument('--keycloak-client-id', '-i',
                    help='The Keycloak client ID, i.e. "data-manager-api-dev"',
                    required=True)
args = parser.parse_args()

# Now get an API token.
# It should be valid for the remainder of the utility...
token: str = Auth.get_access_token(
    keycloak_url='https://' + args.keycloak_hostname + '/auth',
    keycloak_realm=args.keycloak_realm,
    keycloak_client_id=args.keycloak_client_id,
    username=keycloak_user,
    password=keycloak_user_password,
)

Note

That this assumes you hav a Keycloak account with a username and password. If you have only used a federated login (e.g. CAS, GitHub etc.) then you may not have a password. To create one go to your Keycloak account (e.g. https://<server-name>/auth/realms/<realm-name>/account), login with whatever mechanism you use and then give yourself a password in the Password section.

API response data

Depending on which API method is used, when successful, the Data Manager response payload (its JSON content) is returned as a Python dictionary in the DmApiRv.msg property.

For example, when successful the DmApi.start_job_instance() will return the assigned Task and Instance identities.

spec = {'collection': 'im-test', 'job': 'nop', 'version': '1.0.0'}
rv: DmApiRv = v.start_job_instance(
    token,
    project_id=project_id,
    name='My Job',
    specification=spec
)
assert rv.success
rv.msg
{'task_id': 'task-...', 'instance_id': 'instance-...'}

Consult the DM API for up-to-date details of the payloads you can expect.

Errors

If the result of an API call fails (DmApiRv.success is False) an error message can typically be found in the DmApiRv.msg, a dictionary, using the key error.

rv.msg
{'error': 'No API URL defined'}