Using the command-line interface

io_beep_boop includes a command line interface to (hopefully) facilitate the execution of certain tasks with the IO API.

The interface can be invoked by entering the following in environments where the package is installed:

(.venv)$ io-beep-boop

All commands can be suffixed with --help to read their documentation:

(.venv)$ io-beep-boop --help
Usage: io-beep-boop [OPTIONS] COMMAND [ARGS]...

Options:
  -t, --token TEXT  One of the two IO App API tokens of the service you want
                    to use.
  --base-url TEXT   The base URL of the IO App API to use.
  --help            Show this message and exit.

Commands:
  registered-fast
  registered-slow

All tasks require a valid API key obtained from the IO Developer website:

_images/tokens.png — Example key in the IO Developer website.

API keys can be passed programmatically as the --token parameter, or manually when prompted by the CLI:

(.venv)$ io-beep-boop --token="XXXXXXXXXXXXXXXXXXXXXXXXXXXXXX"

(.venv)$ io-beep-boop
Token: XXXXXXXXXXXXXXXXXXXXXXXXXXXXXX

Discover who is registered to a given service

Given a text file containing a list of fiscal codes separated by newlines, io_beep_boop can find which ones are registered to a certain IO service.

Using the fast method

By using the get_subscriptions_on_day() method on all days in a given date range, io_beep_boop can determine the users who registered to the service in those days.

(.venv)$ io-beep-boop registered-fast

Warning

Internally, this uses the /subscription-feed/ endpoint, which is not enabled by default for all API keys, and requires manual approval by the IO Team.

If the token is not enabled to access the endpoint, a httpx.HTTPStatusError will be raised.

$ io-beep-boop registered-fast
...
httpx.HTTPStatusError: Client error '403 Forbidden' for url 'https://api.io.italia.it/api/v1/subscriptions-feed/2022-04-28'
For more information check: https://httpstatuses.com/403

Using the slow method

By using the io_beep_boop.api.client.get_profile() methods on all profiles with the given fiscal codes, io_beep_boop can determine which ones of those users are registered to the service and which ones are not.

(.venv)$ io-beep-boop registered-slow

By default, the method performs a single HTTP request per second, in order to avoid rate limits; this can be changed with the --sleep option:

(.venv)$ io-beep-boop registered-slow --sleep 5.0

Warning

This endpoint performs a HTTP request for every single fiscal code in your given input document, which works, but may not be allowed by IO App API Terms of Service due to the extreme amount of requests possibly generated.

Try to keep the --sleep delay high!