Accessing the Q Replication REST API for Db2

You can access the Q Replication API through an interactive user console or by using cURL commands on a system with network connectivity to the Q Replication REST API server.

Before you begin

Q Replication provides an interactive API console to view and try the product REST API calls before you use them to automate or script replication health checks or setup tasks. These Q Replication REST APIs must be run by a user with DBADM authority. To access the Db2 Replication REST API user interface, you need to have the following information:
  • The hostname of the cluster that contains the database that you want to replicate.
  • The external port number of the Q Replication REST API server.
You can find the REST external port number by running the following command: 
oc get svc -n <db2_instance_namespace>| grep <db2_instance_id> | grep 9444 | sed 's/.*9444://' | sed 's/\/TCP.*//')

About this task

The Q Replication REST API provides you with several tools organized into five categories to develop your own Q Replication-enabled applications:

Health
Monitor the health of the Q Replication environment.
Replication set
  • Create, update, delete, list, start, stop, add, or remove a table.
  • Start or stop replication for tables or list of tables.
  • Add schema-level subscriptions to a set, remove them from a set, and start or stop schema-level subscriptions.
  • Monitor a replication set and get historical metric data.
Source
Enable Q Replication, activate Q Replication, check for requirements, check for a Transport Layer Security (TLS) certificate, validate connectivity, update credentials, and monitor API calls on the source database.
Target
Initialize Q Replication, check requirements, validate connectivity, trust and exchange certificates, update credentials, and monitor API calls on the target database.
Tools and utilities
Check the status of nonconcurrent API calls.
Replication enablement is done through the command line. You can issue Db2 Replication REST API calls by using the Client URL (cURL) command-line tool or through a graphic user interface (GUI).
Note: You can use a cURL command to make Q Replication API calls on a system with network connectivity to the Q Replication API server.

cURL is a free command-line tool that can call the Q Replication REST API on any system that has connectivity to the Q Replication REST API server. The cURL command uses the libcURL client-side URL transfer library, which supports many different transfer protocols, including HTTPS, SMTP, and FTP. Q Replication REST APIs support HTTPS.

cURL command
A cURL command is an API request that you can copy into a command shell or script. If you want to run the cURL command outside of the API console, specify the following options:
  • The Insecure option (-k or --insecure), if you do not have a CA-signed certificate that is installed in your environment.
  • The header (-H or --header) to specify input and output data format, including API server authentication.
  • User authentication (-u or --user), or authorization header (--header 'Authorization: Basic your_basic_token') where your basic token can be generated by using the following:
  • echo <source_db_username>:<source_db_password> | base64
  • Data (-d or --data) sends specified data in a POST request with a body parameter to the Q Replication REST API server.
  • A URL --url to a Q Replication REST API endpoint.
The syntax of a cURL command includes other options. You can include cookies, set proxies, and add authentication credentials in your cURL commands. For more information, run the curl -- help command.
Request URL
The URL that is used when a web client makes a request to a server for a resource.
Response Body
The Java code that is returned from the API call and that you can incorporate into your applications.
Response Code
The response code that is returned from the API call.
Response Headers
An HTTP header that can be used in an HTTP response and that does not relate to the content of the message.
The following procedure focuses on using the third party Swagger GUI to start Q Replication REST API commands.

Procedure

  1. From your web browser, start the Replication REST API user interface. 
    https://hostname:port/api/explorer

    Where hostname is the hostname of the cluster where the source database is running, and port is the external port number of the Q Replication REST API server.

  2. From the Replication REST API user interface, click one of the API categories to display the available API calls.
  3. Click the exclamation mark ( ! ) icon. In the dialog box that opens, enter a user ID and password. These credentials must authorize the user to run commands on the Q Replication source system and access the source database.
  4. To view the usage information and responses from an API call, click Try it out!

    After you call the API, several pieces of information are displayed that describe the specific API call you selected:

    Implementation Notes
    Describes the purpose of the API call.
    Response Messages
    Displays the return code from the API command call that you can use in your application or script.
    Response Class
    Describes the JSON string for the API call result.
    Parameters
    Displays API path parameter, query string parameters, and request body parameters.

    For APIs that require you to provide input parameters in a defined format, the Db2 Replication REST API user interface displays sample parameter values such as dbHost, dbPort, or dbName.

What to do next

Activating Q Replication for Db2