The Account Server API

A module providing simplified assess to the Squonk2 Account Server API.

The API URL

The URL to the Account Server API is taken from the environment variable SQUONK2_ASAPI_URL if it exists. If you do not want to verify the SSL certificate you can also set SQUONK2_ASAPI_VERIFY_SSL_CERT to anything other than "yes", its default value.

If you haven’t set the API URL variables you need to set the Account Server API URL before you can use any API method.

url = 'https://example.com/account-server-api'
AsApi.set_api_url(url)

If the Account Server API is not secure (e.g. you’re developing locally) you can disable the automatic SSL authentication when you set the URL.

AsApi.set_api_url(url, verify_ssl_cert=False)

The API

Python utilities to simplify calls to some parts of the Account Server API that interact with Organisations, Units, Products and Assets.

Note

The URL to the DM API is automatically picked up from the environment variable SQUONK2_ASAPI_URL, expected to be of the form https://example.com/account-server-api. If the variable isn’t set the user must set it programmatically using AsApi.set_api_url().

class squonk2.as_api.AsApi

The AsApi class provides high-level, simplified access to the AS REST API. You can use the request module directly for finer control. This module provides a wrapper around the handling of the request, returning a simplified namedtuple response value AsApiRv

classmethod create_organisation(access_token: str, *, org_name: str, org_owner: str, timeout_s: int = 4) → AsApiRv

Creates an Organisation. You need to provide a name and an owner.

You will need admin privileges to do this.

Parameters

  • access_token – A valid AS API access token

  • org_name – The name to give the Organisation

  • org_owner – The Organisation owner

  • billing_day – A billing day (1..28)

  • timeout_s – The underlying request timeout

classmethod create_product(access_token: str, *, product_name: str, unit_id: str, product_type: str, allowance: int = 0, limit: int = 0, flavour: str = '', timeout_s: int = 4) → AsApiRv

Creates a Product in a Unit.

You will need to be a member of the Organisation or Unit to use this method.

Parameters

  • access_token – A valid AS API access token

  • product_name – The name to assign to the Product

  • unit_id – The Unit UUID for the Product

  • product_type – The product type, e.g. “DATA_MANAGER_PROJECT_TIER_SUBSCRIPTION”

  • allowance – The coin allowance for the product

  • limit – The coin limit for the product

  • flavour – The product flavour (for products that support flavours)

  • timeout_s – The underlying request timeout

classmethod create_unit(access_token: str, *, unit_name: str, org_id: str, billing_day: int, timeout_s: int = 4) → AsApiRv

Creates a Unit for a given an Organisation. You need to provide a name and billing day - a day in the month to bill all the subscription-based products created for the Unit.

You will need to be a member of the Organisation to use this method.

Parameters

  • access_token – A valid AS API access token

  • unit_name – The name to give the Unit

  • org_id – The Organisation UUID for the Unit

  • billing_day – A billing day (1..28)

  • timeout_s – The underlying request timeout

classmethod delete_product(access_token: str, *, product_id: str, timeout_s: int = 4) → AsApiRv

Deletes a Product in a Unit.

You will need to be a member of the Organisation or Unit to use this method.

Parameters

  • access_token – A valid AS API access token

  • product_id – The Unit UUID for the Product

  • timeout_s – The underlying request timeout

classmethod delete_unit(access_token: str, *, unit_id: str, timeout_s: int = 4) → AsApiRv

Deletes a Product in a Unit.

You will need to be a member of the Organisation or Unit to use this method.

Parameters

  • access_token – A valid AS API access token

  • unit_id – The Unit UUID for the Product

  • timeout_s – The underlying request timeout

classmethod get_api_url() → Tuple[str, bool]

Return the API URL and whether validating the SSL layer.

classmethod get_available_assets(access_token: str, *, scope_id: Optional[str] = None, timeout_s: int = 4) → AsApiRv

Returns Assets you have access to. If you provide a scope ID (a username or a product, unit or org UUID) only assets available in that scope will be returned.

Parameters

  • access_token – A valid AS API access token

  • scope_id – Optional scope identity (User or Product, Unit or Org UUID)

  • timeout_s – The underlying request timeout

classmethod get_available_products(access_token: str, *, timeout_s: int = 4) → AsApiRv

Returns Products you have access to.

Parameters

  • access_token – A valid AS API access token

  • timeout_s – The underlying request timeout

classmethod get_available_units(access_token: str, *, timeout_s: int = 4) → AsApiRv

Returns Units (and their Organisations) you have access to.

Parameters

  • access_token – A valid AS API access token

  • timeout_s – The underlying request timeout

classmethod get_merchants(access_token: str, *, timeout_s: int = 4) → AsApiRv

Returns Merchants known (registered) with the Account Server.

Parameters

  • access_token – A valid AS API access token

  • timeout_s – The underlying request timeout

classmethod get_organisation(access_token: str, *, org_id: str, timeout_s: int = 4) → AsApiRv

Gets an Organisation.

You will need to be a member of the Organisation to use this method.

Parameters

  • access_token – A valid AS API access token

  • org_id – The Organisation UUID

  • timeout_s – The underlying request timeout

classmethod get_organisations(access_token: str, *, timeout_s: int = 4) → AsApiRv

Gets all the Organisations you can see.

Parameters

  • access_token – A valid AS API access token

  • timeout_s – The underlying request timeout

classmethod get_product(access_token: str, *, product_id: str, timeout_s: int = 4) → AsApiRv

Returns details for a given Product.

Parameters

  • access_token – A valid AS API access token

  • product_id – The UUID of the Product

  • timeout_s – The underlying request timeout

classmethod get_product_charges(access_token: str, *, product_id: str, from_: Optional[date] = None, until: Optional[date] = None, timeout_s: int = 4) → AsApiRv

Returns charges for a given Product. If from and until are omitted charges for the current billing period are returned.

You will need admin rights on the Account Server to use this method.

Parameters

  • access_token – A valid AS API access token

  • product_id – The UUID of the Product

  • from – An option date where charges are to start (inclusive)

  • until – An option date where charges are to end (exclusive)

  • timeout_s – The underlying request timeout

classmethod get_products_for_organisation(access_token: str, *, org_id: str, timeout_s: int = 4) → AsApiRv

Returns Products for a given Organisation.

Parameters

  • access_token – A valid AS API access token

  • org_id – The UUID of the Organisation

  • timeout_s – The underlying request timeout

classmethod get_products_for_unit(access_token: str, *, unit_id: str, timeout_s: int = 4) → AsApiRv

Returns Products for a given Unit.

Parameters

  • access_token – A valid AS API access token

  • unit_id – The UUID of the Unit

  • timeout_s – The underlying request timeout

classmethod get_unit(access_token: str, *, unit_id: str, timeout_s: int = 4) → AsApiRv

Gets a Unit.

You will need to be a member of the Organisation or Unit to use this method.

Parameters

  • access_token – A valid AS API access token

  • unit_id – The UUID for the Unit

  • timeout_s – The underlying request timeout

classmethod get_units(access_token: str, *, org_id: str, timeout_s: int = 4) → AsApiRv

Gets Units in an Organisation.

You will need to be a member of the Organisation to use this method.

Parameters

  • access_token – A valid AS API access token

  • org_id – The Organisation UUID for the Unit

  • timeout_s – The underlying request timeout

classmethod get_version(*, timeout_s: int = 4) → AsApiRv

Returns the AS-API service version.

Parameters

timeout_s – The underlying request timeout

classmethod ping(*, timeout_s: int = 4) → AsApiRv

A handy API method that calls the AS API to ensure the server is responding.

Parameters

timeout_s – The underlying request timeout

classmethod set_api_url(url: str, *, verify_ssl_cert: bool = True) → None

Replaces the API URL value, which is otherwise set using the SQUONK2_ASAPI_URL environment variable.

Parameters

  • url – The API endpoint, typically https://example.com/account-server-api

  • verify_ssl_cert – Use False to avoid SSL verification in request calls

class squonk2.as_api.AsApiRv(success: bool, msg: Dict[Any, Any])

The return value from most of the the AsApi class public methods.

Parameters

  • success – True if the call was successful, False otherwise.

  • msg – API request response content