Using REST API

Use the OCI GoldenGate REST API to communicate with your data replication deployments. Discover how to use the REST API in various configurations, invoking commands using curl and Cloud Shell.

Connect to a public deployment

To connect to an OCI GoldenGate deployment with a public endpoint in Cloud Shell, you only need the deployment URL. You can find the deployment URL (Console URL) on the deployment's details page.

Connect to a private deployment

If the deployment has a private endpoint, you can connect Cloud Shell to a network with access to the deployment using Cloud Shell Networking, or create a bastion, bastion session, and SSH tunnel.

By default, Cloud Shell limits network access to OCI internal resources in your tenancy home region unless you have enabled the Cloud Shell managed Public Network. Your administrator must configure an Identity policy to enable Cloud Shell Public Network. For more information, see Cloud Shell Networking.

To connect to a private OCI GoldenGate deployment in Admin Client:
  1. In the Oracle Cloud console global navigation bar, click Developer tools, and then Cloud Shell.
    Note

    If this is your first time connecting to Cloud Shell, it may take a few minutes to connect.
  2. (Optional) Run the following command to generate SSH keys. You can skip this step if you want to generate the keys when you create the bastion.
    ssh-key gen -t rsa

    Keep the default file name and don't enter a passphrase when prompted. The private key is located at ~/ssh/id_rsa and the public key is located at ~/ssh/id_rsa.pub.

  3. On the deployment details page, take note of the deployment's private IP and subnet information.
  4. Create a bastion:
    1. From the Oracle Cloud console navigation menu, select Identity & Security, and then Bastion.
    2. On the Bastion page, click Create bastion.
    3. In the Create bastion page, enter a name, and then select the same subnet where the deployment resides.
    4. For CIDR block allowlist, enter 0.0.0.0/0.
    5. Click Create bastion.
  5. After the bastion is Active, create a session:
    1. On the bastion details page, click Create session.
    2. On the Create session page, for Session type, select SSH port forwarding session.
    3. Enter a Session name.
    4. For Connect to target host by using, select IP address, and then enter the deployment's private IP address.
    5. For Port, enter 443.
    6. For Add SSH key, select one of the following options:
      • Paste SSH key, and paste the contents of the public key ((~/ssh/id_rsa.pub) created in Cloud Shell in Step 2 above.
      • Generate an SSH key pair
    7. Click Create session.
  6. After the session is Active, select View SSH command from its Action menu (ellipsis icon).
  7. In the View SSH command dialog, enter the path to the private key (~/ssh/id_rsa) in place of <private-key> and replace <local-port> with the port in Cloud Shell that will forward the connection to the bastion.
    Note

    Cloud Shell doesn't allow port forwarding on a privileged port with sudo access, so you must use a non-privileged port like 7443. After the command runs once in the foreground to add the Bastion host to known_hosts, you can append an ampersand (&) to the end of the command so that it can run in the background next time.
  8. Copy the command and then run it in Cloud Shell. You can ignore the bind: Cannot assign requested address messages.

Example REST API calls

Optionally, you can store your deployment username and password into a .netrc file. The following examples assume you're using a .netrc file.

You can now send requests to your data replication deployment using curl. For example, the following command returns the deployment health:
curl -n -H "Content-Type: application/json" -H "Accept: application/json" -X GET https://<deployment URL>/services/v2/config/health

List Trail files

curl -n -H "Content-Type: application/json" -H "Accept: application/json" -X GET https://<deployment URL>/services/v2/exttrails

List Extracts or Replicats

List Extracts:
curl -n -H "Content-Type: application/json" -H "Accept: application/json" -X GET https://<deployment URL>/v2/extracts
List Replicats:
curl -n -H "Content-Type: application/json" -H "Accept: application/json" -X GET https://<deployment URL>/v2/replicats

Retrieve Extract or Replicat details

Retrieve Extract details:
curl -n -H "Content-Type: application/json" -H "Accept: application/json" -X GET https://<deployment URL>/v2/extracts/<extract name>
Retrieve Replicat details:
curl -n -H "Content-Type: application/json" -H "Accept: application/json" -X GET https://<deployment URL>/v2/replicats/<replicat name>

Create an Extract

First, create a JSON document containing the Extract configuration. For example, this file can be used to generate an Extract called EATP using the E1 trail and capturing data from SRC_OCIGGLL.*:
{
        "config":[
                "Extract EATP",
                "ExtTrail E1",
                "UseridAlias BLOGSRCATP", 
                "Table SRC_OCIGGLL.*;"
        ], 
        "source":{"tranlogs":"integrated"},
        "credentials":{"alias":"BLOGSRCATP"},
        "registration":{"optimized":false},
        "begin":"now",
        "targets":[{"name":"E1"}]
}
Then, run the following command to create the Extract process:
curl -n -H "Content-Type: application/json" -H "Accept: application/json" -X POST https://<deployment URL>/services/v2/extracts/<Extract name> -d @<JSON file>.json

Create a Replicat

First, create a JSON document containing the Replicat configuration. For example, this file can be used to generate a Replicat called RADW using the E1 trail and replicating data from SRC_OCIGGLL.* into SRCMIRROR_OCIGGLL.*:
{
        "config":[
                "REPLICAT RADW",
                "UseridAlias BLOGTRGADW",
                "MAP SRC_OCIGGLL.*, TARGET SRCMIRROR_OCIGGLL.*;"
        ],  
        "source":{"name": "E1"},
        "credentials":{"alias":"BLOGTRGADW"},
        "checkpoint":{"table":"SRCMIRROR_OCIGGLL.CHECKTABLE"},
        "mode":{
                "type":"nonintegrated",
                "parallel": false
        },
        "registration":"none",
        "begin":"now",
        "status":"stopped"
}
Then, run the following command to create the Replicat process:
curl -n -H "Content-Type: application/json" -H "Accept: application/json" -X POST https://<deployment URL>/services/v2/replicats/<Replicat name> -d @<JSON file>.json

Start an Extract or Replicat

curl -n -H "Content-Type: application/json" -H "Accept: application/json" -X POST https://<deployment URL>/services/v2/commands/execute -d '{ "name":"start", "processName":"<Extract or Replicat name>"}'

Get the status and statistics for a given Extract

Get Extract status:
curl -n -H "Content-Type: application/json" -H "Accept: application/json" -X POST https://<deployment URL>:<port>/services/v2/extracts/<extract name>/command -d '{"command":"STATUS"}'
Get Extract statistics:
curl -n -H "Content-Type: application/json" -H "Accept: application/json" -X POST https://<deployment URL>:<port>/services/v2/extracts/<extract name>/command -d '{"command":"STATUS"}'

Get the status and statistics for a given Replicat

Get Replicat status:
curl -n -H "Content-Type: application/json" -H "Accept: application/json" -X POST https://<deployment URL>:<port>/services/v2/replicats/<replicat name>/command -d '{"command":"STATUS"}'
Get Replicat statistics:
curl -n -H "Content-Type: application/json" -H "Accept: application/json" -X POST https://<deployment URL>:<port>/services/v2/replicats/<replicat name>/command -d '{"command":"STATS"}'