What it is

oggrestapi is a Python package that wraps the GoldenGate Microservices REST API - around 300 methods, generated from Oracle's Swagger definitions and normalized so every action follows the same naming pattern: list_ for collections, get_ for a single resource, and create_ / update_ / delete_ for the matching write operations. Instead of building URLs and parsing JSON by hand with requests, you call a method with plain arguments.

It's a single class that works across GoldenGate versions (26ai, 23ai, and 19c), handling the endpoint and payload differences between them internally rather than making you pick a version-specific class.

Install

pip install oggrestapi

The pip package isn't required to use the class: it's a single oggrestapi.py file with no dependencies beyond requests, so you can also just download that file from GitHub and drop it next to your script.

Quick start

from oggrestapi import OGGRestAPI

# Connect directly to one service (here the Administration Service, port 7810)
ogg_client = OGGRestAPI(url="http://vmogg:7810", username="ogg", password="ogg")
# Silent by default; pass verbose=True to log a confirmation line once connected.

Omit the password to be prompted for it securely instead of hardcoding it:

>>> ogg_client = OGGRestAPI(url="http://vmogg:7810", username="ogg", verbose=True)
Password for ogg:
Connected to OGG REST API at http://vmogg:7810

It also supports the context-manager protocol, so the underlying HTTP session is always closed for you:

with OGGRestAPI(url="http://vmogg:7809", username="ogg") as ogg_client:
    print(ogg_client.list_deployments())

Reaching a whole deployment

Connecting straight to one service's own port (as above) is enough for one-off calls, but a deployment's extracts and replicats live behind that deployment's administration service (default port 7810), separate from the Service Manager's own port (default 7809) that lists deployments in the first place - so a script touching both ends up juggling two clients. Two connection modes avoid that:

Behind an NGINX reverse proxy, route to a deployment by name through a single URL:

# Behind an NGINX reverse proxy: one URL, many deployments, pick one by name
ogg_client = OGGRestAPI(
    url="https://vmogg",
    username="ogg",
    deployment="ogg_test_01",
    reverse_proxy=True,
)

Without a reverse proxy, point at the Service Manager and let the client discover each service's port itself:

# No reverse proxy, but don't want to juggle a client per port: point at the
# Service Manager (7809) with a deployment name, and each service's own port
# (adminsrvr, distsrvr, ...) is looked up automatically the first time you use it.
ogg_client = OGGRestAPI(
    url="http://vmogg:7809",
    username="ogg",
    deployment="ogg_test_01",
    auto_discovery=True,
)

A raw API call to create a GoldenGate user looks like this with plain requests:

result = requests.post(
    f"http://vmogg:7809/services/v2/authorizations/User/ogg_username",
    auth=("ogg_user", "ogg_password"),
    json={"credential": "your_password"},
)

The same call with the client:

ogg_client.create_user(
    user="ogg_username",
    role="User",
    data={"credential": "your_password"}
)

A few more calls to get a feel for it:

>>> ogg_client.list_deployments()
[{'name': 'ServiceManager', 'status': 'running'}, {'name': 'ogg_test_01', 'status': 'running'}]

>>> ogg_client.list_extracts()
[{'name': 'EXT01', 'status': 'stopped'}, {'name': 'EXT02', 'status': 'running'}]

>>> ogg_client.get_task('purge_aa')
{'enabled': True, 'critical': False, 'status': 'stopped', ...}

>>> ogg_client.create_extract(
...     extract='extn',
...     data={
...         "description": "Region North",
...         "config": [
...             "EXTRACT extn",
...             "EXTTRAIL north/ea",
...             "USERIDALIAS ggnorth",
...             "SOURCECATALOG dbnorth_pdb1",
...             "TABLE hr.*;"
...         ],
...         "source": "tranlogs",
...         "credentials": {"alias": "ggnorth"},
...         "registration": {"optimized": False, "containers": ["dbnorth_pdb1"], "replace": True},
...         "begin": "now",
...         "targets": [{"name": "ea", "path": "north/"}]
...     }
... )

Full documentation and source

The complete method reference, connection options, and design notes are in Production-ready GoldenGate REST client in Python. The package is on PyPI, and the source is on GitHub.

Blog posts using this script