Core - MetabaseApi#

The MetabaseApi class is the core component of the API wrapper and you’ll need to get it started before you do anything else.

Authentication#

There are 3 authentication options currently supported:

Option 2 - Token file#

This option is best when you’ve previously authenticated with username and password and wish to reuse the same token. You can pass the path as a string or a pathlib.Path object.

1import metabase_tools
2
3metabase_url = "http://localhost:3000"
4token_path = "./metabase.token"
5api = metabase_tools.MetabaseApi(metabase_url=metabase_url, token_path=token_path)

Contents of metabase.token:

6117922c-541b-4f58-815e-637c6f362920

Option 3 - Token dictionary#

This option involves getting the token string from your Metabase cookie so is much more involved than the other two.

1import metabase_tools
2
3metabase_url = "http://localhost:3000"
4credentials = {"token": "6117922c-541b-4f58-815e-637c6f362920"}
5api = metabase_tools.MetabaseApi(metabase_url=metabase_url, credentials=credentials)

Caching Tokens#

If you would like to cache your token for future runs to speed things up, simply set cache_token option to True. This option works regardless of which authentication method was used. The token will be saved to token_path.

1import metabase_tools
2
3metabase_url = "http://localhost:3000"
4credentials = {"username": "jim@dundermifflin.com", "password": "BAZouVa3saWgW89z"}
5api = metabase_tools.MetabaseApi(
6    metabase_url=metabase_url, credentials=credentials, cache_token=True
7)

Custom Session objects#

If you need to make use of a proxy or other feature supported by the requests module’s Session class, you can pass it in to the adapter on creation using the session keyword argument.

Other Public Methods#

Testing for successful authentication#

Authentication will be tested during initialization but if you would like to test after that, you can call the test_for_auth method. This will make a test call to the Metabase API and return True if it completed without issue or False otherwise.

metabase_tools.MetabaseApi.test_for_auth(self)#

Validates successful authentication by attempting to retrieve data about the current user

Returns:

Authentication success status

Return type:

bool

Making generic requests#

To make custom calls to the Metabase API, you can use the generic_request method. In general, it’s better to use class-specific methods to call the methods you need but this can be used for unsupported endpoints while still utilizing the cached authentication of the wrapper.

metabase_tools.MetabaseApi.generic_request(self, http_verb, endpoint, params=None, json=None)#

Method for dispatching HTTP requests

Parameters:

  • http_method (str) – GET or POST or PUT or DELETE

  • endpoint (str) – URL endpoint

  • params (dict, optional) – Endpoint parameters

  • json (dict, optional) – Data payload

  • http_verb (Literal['GET', 'POST', 'PUT', 'DELETE']) –

Raises:

  • InvalidDataReceived – Unable to decode response from API

  • AuthenticationFailure – Auth failure received from API

  • RequestFailure – Other failure during request

Returns:

Response from API

Return type:

list[dict[str, Any]] | dict[str, Any]

For convenience, there are also methods to utilize for get, delete, post, and put HTTP verbs:

metabase_tools.MetabaseApi.get(self, endpoint, params=None)#

HTTP GET request

Parameters:

  • endpoint (str) – URL endpoint

  • ep_params (dict, optional) – Endpoint parameters

  • params (dict[str, Any] | None) –

Returns:

Response from API

Return type:

list[dict[str, Any]] | dict[str, Any]

metabase_tools.MetabaseApi.delete(self, endpoint, params=None)#

HTTP DELETE request

Parameters:

  • endpoint (str) – URL endpoint

  • params (dict, optional) – Endpoint parameters

Returns:

Response from API

Return type:

list[dict[str, Any]] | dict[str, Any]

metabase_tools.MetabaseApi.post(self, endpoint, params=None, json=None)#

HTTP POST request

Parameters:

  • endpoint (str) – URL endpoint

  • params (dict, optional) – Endpoint parameters

  • json (dict, optional) – Data payload

Returns:

Response from API

Return type:

list[dict[str, Any]] | dict[str, Any]

metabase_tools.MetabaseApi.put(self, endpoint, params=None, json=None)#

HTTP PUT request

Parameters:

  • endpoint (str) – URL endpoint

  • ep_params (dict, optional) – Endpoint parameters

  • json (dict, optional) – Data payload

  • params (dict[str, Any] | None) –

Returns:

Response from API

Return type:

list[dict[str, Any]] | dict[str, Any]