DB2 v11.5.4 REST API – Part One
Part One – Setup and Configuration
Enabling clients to interact via HTTP GET/POST requests the REST API functionality provides clients a lightweight, modern interface to data stored in DB2 databases. In this series we look at how to get started with the REST API from the DBA’s perspective, starting in part one with how to get the service up and running.
Installation of the IBM Cloud CLI
The REST API functionality is delivered separately from the DB2 product itself in a Docker container. This container has to be downloaded from the IBM cloud, and requires both an IBM cloud account and the IBM Cloud CLI to be installed. I did try to login directly to the IBM Container Registry using an API key with docker which succeeded, however attempting to pull the image resulted in an unauthorised error. I don’t think that is ideal, as frankly you may not want to install the IBM Cloud CLI on the machine that runs your containers – it might not even directly connect to the internet – hopefully this will change in the future so the container image can be downloaded from somewhere like Passport Advantage.
As there doesn’t seem to currently be a way around it, I created a VM and installed the IBM Cloud CLI and tools as per the instructions found here: https://cloud.ibm.com/docs/cli?topic=cli-getting-started.
This took a couple of minutes to install the CLI and associated software. Unfortunately using Red Hat Linux 7.8 the Docker installation failed as the repository link is not valid:
It seems slightly ironic that IBM Cloud and Red Hat Linux aren’t playing nicely. To quickly get around the issue I cheated slightly and used the Centos repository instead:
A simple ‘yum install docker’ then got me back on track. If you install manually like this don’t forget to start the Docker service once it is installed using ‘systemctl start docker’.
Next up configure your login for IBM Cloud on the command line. As I don’t have a GUI on this server I copied the link into a browser to get the One Time Code which worked fine.
Once the login is configured, set your region and then log in:
Downloading the DB2 REST API Image
Now we are logged in Docker can pull the image from the IBM Cloud Container Registry. If you want to run the container on this server you can simply use the docker pull command and then skip the rest of this section – I want to run the container on a different server however, so after the pull I used the docker save command to export the image into a file that can then be copied:
Once the file is copied to the server where I want the container to run, I used docker load to import the image. Handily there is no need to unzip:
The docker images command confirms we have the image stored locally for Docker to run, so it’s time to spin up the container.
Start the Container and Configure the REST Service
The docker run command supplied by IBM will start the container sharing the host networking and listening on port 50050 – you may need to map that port if it is already in use, but for me the default configuration was fine. One change I would probably recommend if this container is going to be used seriously would be to add some restart logic – if you’re just using Docker the run command has a –restart flag that can be set to bring the container back up if it stops for any reason.
The docker ps command confirms the container is running, so now it’s time to configure the REST service to connect to connect to a database. You can run the configuration commands either inside or outside of the container, I chose inside:
The setup command takes arguments of db_host, db_name, db_port, ssl_enabled, db_user, db_password.
Looking at the database we can see a new table in the DB2REST schema (currently empty):
And a couple of new SQL stored procedures:
We’ll take a closer look at these objects later in the blog series when we start to create and maintain services, for now they suffice to confirm the REST service has successfully connected to the database and set up the required objects.
The last thing to do as part of setup is to confirm the REST service itself is up and accessible, as suggested by the manual you can do this by viewing the documentation that the service itself makes available at https://<hostname>:50050/docs:
The certificate error is also something we’ll be revisiting later, but just seeing the documentation means the service is running and we can talk to it.
Conclusion
Installation and setup of the REST service was relatively trouble-free with only the Docker installation during the IBM Cloud CLI setup causing an issue, which I suspect is out of the hands of the DB2 development guys. I would like to see more flexibility in how the software can be obtained but for now at least it’s possible to copy the image to a secure server once it’s been downloaded.
In the next part of this blog series we’ll put the DB2 REST capabilities to work by creating and calling services.
Leave a Reply