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_organisation_charges(access_token: str, *, org_id: str, from_: Optional[date] = None, until: Optional[date] = None, pbp: Optional[int] = None, timeout_s: int = 4) AsApiRv
Returns charges for a given Organisation. 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
org_id – The UUID of the Organisation
from – An optional date where charges are to start (inclusive)
until – An optional date where charges are to end (exclusive)
pbp – An optional prior billing period
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, pbp: Optional[int] = 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 optional date where charges are to start (inclusive)
until – An optional date where charges are to end (exclusive)
pbp – An optional prior billing period
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