Omni API

Simple REST API wrapper for the Omni infra-structure.

Configuration

Usage

Typical usage of the Omni client implies the providing of the username and the password inside the target omni instance (Direct Mode).

api = omni.Api(
    base_url = "http://frontdoorhq.com",
    username = "YOUR_USERNAME",
    password = "YOUR_PASSWORD"
)

Alternatively it's possible to use the api throught an OAuth base approach using the provided client id and secret values.

api = omni.Api(
    base_url = "http://frontdoorhq.com",
    client_id = "YOUR_OAUTH_ID",
    client_secret = "YOUR_OAUTH_SECRET"
)

For these type of handling the OAuthAccessError exception must be handled and then the user must be redirect to the url provided by api.oauth_autorize method call.

Running then the api.oauth_access call with the returned code from the server side that should be used to redeem the access_token required for session authentication.

Documentation

See the documentation index.

Examples

Examples are located here.

Testing

The unit test suite runs using pytest and requires Python 3.10+, unlike the library itself the tests make full use of the provided type stubs (the library implementation remains Python 2.7+ compatible).

pip install pytest
pytest

The live integration tests run against a local Omni instance and are skipped unless the OMNI_TEST_LIVE environment variable is set, together with the usual OMNI_BASE_URL, OMNI_USERNAME and OMNI_PASSWORD configuration.

Such an instance can be provisioned with demo data using the hivesolutions/omni docker image (private, registry credentials required), the loader seeds the database with the demo dataset (including the root / Root@12345 credentials) and the server is then started, note that with COLONY_PREFIX=/mvc the client base URL should not include the /mvc prefix:

docker run -d --name omni -p 8080:8080 --entrypoint sh \
    -e RUN_MODE=development \
    -e COLONY_CONFIG_FILE=config/python/singleton.py \
    -e DB_ENGINE=sqlite \
    -e DB_FILE=ci.db \
    -e RESET_DB=1 \
    -e AT_TEST_MODE=1 \
    hivesolutions/omni:latest \
    -c "cd /omni && python3 scripts/load_demo_data.py && exec colony_wsgi"
OMNI_TEST_LIVE=1 OMNI_BASE_URL=http://localhost:8080/ OMNI_USERNAME=root OMNI_PASSWORD=Root@12345 pytest

The CI pipeline runs the same provisioning in the Build Live job whenever the Docker Hub credentials are available as repository secrets (DOCKERHUB_USERNAME and DOCKERHUB_TOKEN), skipping the live run otherwise.

Type checking of the stubs, examples and tests is done using Pyright:

pip install pyright
pyright src/omni/*.pyi src/examples src/omni/test

License

Omni API is currently licensed under the Apache License, Version 2.0.

Build Automation