The HTTP API is described by the openapi.yaml according to OpenAPI Specification. The base of the server (e.g., entity models) was generated by the OpenAPI Generator project. This includes ALL the contents of the server/fleetv2_http_api directory EXCEPT for:

• impl,
• controllers/security_controller.py (originally created by the Generator).

These files are included in the server/.openapi-generator-ignore. This file also must include itself.

Formal specification can be found as part of HTTP API document.

Python 3.10.12+

The configuration file is located in config directory. The file contains the fields listed below.

Check carefully the correct name of the database the server should connect to.

• logging - contains the keys consoleand file for printing the logs into a console and a file, respectively. The file contains field path to set the (absolute or relative) path to the directory to store the logs. Both contain the following keys:
  • level - logging level as a string (DEBUG, INFO, WARNING, ERROR, CRITICAL). Case-insensitive.
  • use - set to True to allow to print the logs, otherwise set to False.
• database - settings for the database associated with the server.
  • server - settings for the database server. If only path is provided under server, the database used will be an sqlite file specified by the path.
    • username
    • password
    • location - location of the database (e.g., localhost).
    • port - port number.
    • database-name - database name.
    • path - only use this parameter if an sqlite db is needed (no other fields can be used in server in that case, otherwise connection to postgresql will we attempted). The value should be a path to a database file (e.g., /home/user/test.db). The file will be created if it doesn't exist.
  • cleanup - contains the following keys:
    • timing_in_seconds
      • retention_period- number of seconds after which each message can be deleted after it has been posted to the server.
      • cleanup_period - number of seconds after which the cleanup process will be executed.
• http_server- contains the following keys: base_uri- base URI of the HTTP server (e.g., http://localhost:8080).
• request_for_messages
  • timeout_in_seconds - number of seconds after which the server will stop waiting for messages from the client and returns empty response.
• security field is further described in the section Configuring oAuth2.

Install python dependencies into an activated virtual environment:

python3 -m venv .venv && \
source .venv/bin/activate && \
pip3 install -r requirements.txt

To run the server execute the following:

python3 -m server <path-to-config-file> [OPTIONS]

The server automatically connects to the PostgreSQL database using data from the config file. If you want to override these values, start the server with some of the following options:

Note that these data should comply with the requirements specified in SQLAlchemy documentation.

To visualize the API, open your browser here (the location and port may vary according to the script parameters or the values in config/config.json):

http://localhost:8080/v2/protocol/ui

Your OpenAPI definition lives here:

http://localhost:8080/v2/protocol/openapi.json

To generate a new api_key (passed as a query parameter "api_key") run the following:

python scripts/new_admin.py <new-admin-name> <path-to-config-file> [OPTIONS]

The script automatically connects to the PostgreSQL database using the config file. To override any of those values, run the script with some of the following options:

Note that these data should comply with the requirements specified in SQLAlchemy documentation.

Working example for test database built from docker-compose (username and password can be found in the config/config.json).

python scripts/new_admin.py 'Bob' config/config.json

After running the script, the api_key is printed to the console:

New key for admin 'Bob':

<generated-api-key>

To run the server on a Docker container, run:

docker compose up --build -d

To get Keycloak authentication working, all parameters in the security section of config/config.json need to be filled in. Most information is found in the Keycloak GUI.

"security": {
        "keycloak_url": "https://keycloak.bringauto.com",
        "client_id": "",
        "client_secret_key": "",
        "scope": "",
        "realm": ""
    }

• keycloak_url: base URL of a working Keycloak instance
• client_id: id of client in Keycloak (Clients -> click on client representing HTTP API -> Settings -> Client ID)
• client_secret_key: secret key of client (Clients -> click on client representing HTTP API -> Credentials -> Client Secret)
• scope: checking of scopes is not yet implemented (must be email for now!)
• realm: realm in which the client belongs (seen on top of the left side panel in Keycloak GUI)

The server settings can be found in the config/config.json, including the database logging information and parameters for the database cleanup.

Testing of a cloned repository requires two steps:

• install this package,
• run the tests (or their subset).

Before installation, make sure you have the virtual environment activated. This is a necessary step to avoid conflicts with the system packages.

In the root directory, run the following

python -m tests [-h] [PATH1] [PATH2] ...

Each PATH is specified relative to the tests directory. If no PATH is specified, all the tests will run. Otherwise

• when PATH is a directory, the script will run all tests in this directory (and subdirectories),
• when PATH is a Python file, the script will run all tests in the file.

The -h flag makes the script display tests' coverage in an HTML format, for example in your web browser.

The same applies to integration tests using containerized HTTP servers.

To run the integration tests, run the following in the root directory:

python -m tests_integration [-h] [PATH1] [PATH2] ...

You must have the OpenAPI Generator installed (see link). Before the server generation, the server must not be running.

To regenerate the server, run (in the server directory):

openapi-generator-cli generate -g python-flask -i ../openapi.yaml -o . -p=packageName=fleetv2_http_api

Below is an example of running the Generator with the port number being specified (the default is 8080):

openapi-generator-cli generate -g python-flask -i ../openapi.yaml -o . -p=packageName=fleetv2_http_api,serverPort=<port-number>

If you have trouble with running the generator, visit docs.