Omni API

Simple REST API wrapper for the Omni infra-structure.

Configuration

Name	Type	Description
OMNI_BASE_URL	`str`	The base URL that is going to be used for API connections (defaults to `http://localhost:8080/mvc/`).
OMNI_OPEN_URL	`str`	The open URL for the Omni connection (defaults to `OMNI_BASE_URL`).
OMNI_PREFIX	`str`	The default prefix to be used for API requests (defaults to `adm/`).
OMNI_ID	`str`	The client id to be used for API connections (defaults to `None`).
OMNI_SECRET	`str`	The secret key to be used for API connections (defaults to `None`).
OMNI_REDIRECT_URL	`str`	The URL to be used for redirection OAuth based workflow (defaults to `base,base.user,base.admin,foundation.store.list`).
OMNI_USERNAME	`str`	The username to be used on direct workflow (defaults to `None`).
OMNI_PASSWORD	`str`	The password to be used on direct workflow (defaults to `None`).

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

Metadata

Release files for omni-api 0.13.0

For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.

Source distribution (sdist)

Source distribution for omni-api 0.13.0
File	Size	Uploaded
omni_api-0.13.0.tar.gz	36.7 kB	Oct 6, 2026	Details

Built distribution (wheel)

Table of built distributions (wheels) for omni-api 0.13.0
File	Interpreter	ABI	Platform	Reset
omni_api-0.13.0-py2.py3-none-any.whl 102.8 kB Oct 6, 2026	Python 2, Python 3	none	any	Details

Total release size: 139.5 kB

Release files / omni_api-0.13.0.tar.gz

Download URL	omni_api-0.13.0.tar.gz
Size	36.7 kB
Tags	Source
SHA-256 checksum How to use checksums	`df7879d79b978c34aa0d9705e59a5330e4edba231a0247aed9c79b91834158de`
BLAKE2b-256 checksum How to use checksums	`013ac69373b2e834727d4534dbf35dff0df865f96cd3543671260cea072a8874`
Upload date	Oct 6, 2026
Uploaded using Trusted Publishing? What is trusted publishing?	No
Uploaded via	`twine/7.0.0 CPython/3.12.15`

Release files / omni_api-0.13.0-py2.py3-none-any.whl

Download URL	omni_api-0.13.0-py2.py3-none-any.whl
Size	102.8 kB
Tags	Python 2 Python 3
SHA-256 checksum How to use checksums	`9d0db84fdb33bc54e51245173a0bd06db4e9c337022eae84f8b60c5dfee90cd8`
BLAKE2b-256 checksum How to use checksums	`574bc510a48d94377966d310591d4fc84c9fd0eca8573f5af4fc7313d409cbaa`
Upload date	Oct 6, 2026
Uploaded using Trusted Publishing? What is trusted publishing?	No
Uploaded via	`twine/7.0.0 CPython/3.12.15`