DB2 Native REST API – Python

Introduction

Whilst I haven’t used Python for a while, it has always been the playground for geeks. With it’s C-like look and feel and it’s huge array of extension libraries there’s very little it can’t do.

I was prompted to refresh my acquaintance with Python by a colleague who’d been reading this blog chain – this is the 10^th in the series – and asked how to go about doing it.

The examples here are all done using (at the time of writing) the latest version of Python on Windows and the Requests module:

Requests is an extension library that provides support for making HTTP(S) calls.

 

What is Python?

An interpreted scripting language that’s semantically quite a bit like C/C++. Python defines itself on the https://python.org/about page on its website as:

Python is powerful… and fast;
plays well with others;
runs everywhere;
is friendly and easy to learn;
is Open.

Python has a lot of built in functionality, but occasionally we have to reach out for another package to add some additional support. In the code examples we’ll look at below, we’re going to make use of the Requests (https://docs.python-requests.org/en/master/)  library. This simplifies making HTTP and HTTPS calls – which is what the REST API is based on. To check if you’ve got it installed, try the following:

 

If you get “ModuleNotFound” in response to the “import requests”, then you will need to install it. With Python for Windows 3.7, this was as simple as requesting it with the Python package manager:

pip install requests

You can find all of the code examples used in this blog on GitHub:

https://github.com/db2dinosaur/db2-rest-python-samples

 

Creating a Simple Service

As we’ve seen in previous posts, as well as using the BIND SERVICE TSO/Batch, we can create a service using the REST API itself. This is done by issuing an HTTP(S) POST to the DB2ServiceManager, like this:

https://github.com/db2dinosaur/db2-rest-python-samples/blob/master/crGetDepartments.py

 

In this example we:

1. Import libraries to provide support for:
   1. Base64 encoding – used to obfuscate the userid and password
   2. Requests using HTTP/HTTPS
   3. JSON – used to send request parameters and encode responses
   4. System – console printing to stdout
2. Define the request body – data – that will be passed as the parameter block to the DB2 Service Manager, then convert it into JSON.
3. Setup the request headers, including the authorisation string (authenticating with user MYUSER using password xxxxxxxx)
4. Issue the request
5. Report the status, headers and response

Here’s the output from running it:

Making a Simple REST Request

As seen above, driving REST services from Python is fairly simple. This next example is even more simple, as the service that we just created has no parameters to pass – we’ll cover that again in the next section.

To drive the service, we’re largely reusing the code that we used to define it:

https://github.com/db2dinosaur/db2-rest-python-samples/blob/master/driveGetDepartments.py

 

Making an AT-TLS Encrypted REST Request

As with previous blogs, there are two types of request that we can drive using the DB2 for z/OS encrypted port (SECPORT):

1. HTTPS encrypted and authenticating with a base64 encoded userid and password
2. HTTPS encrypted and authenticating with a client certificate

Both of these require that the client (Python) trusts the certificate that DB2 uses to verify its identity and key the first stage of the encryption handshake. As with previous examples, we are using certificates generated by RACF, so we need to share the public RACF root certificate (used to sign all of the others) with the client. We can do this in the request by setting the “verify” parameter to point to the file containing the public RACF root Certificate Authority (CA) certificate:

https://github.com/db2dinosaur/db2-rest-python-samples/blob/master/driveTLSNCGetDepartments.py

 

Note the change of port (to the DB2 secure port) and the additional “verify” parameter on the POST request, which gives the location of the CA certificate.

We can also authenticate with DB2 by using a client certificate. This can be installed in, or generated by RACF and associated with a mainframe userid. When presented in place of a userid/password it is verified by RACF and the associated userid used. As an example, we have created a certificate in RACF and associated it with userid ADCDA. This is then exported and downloaded to the client machine, where it is split into the public certificate and private key files. The creation of all of the certificates, how to export them and how to then split the client certificate into public certificate and private key files is covered in the 6^th blog, here (see the sections headed zpdtca.pem and zpdt_webclient.p12).

Here’s an example of how we use these in the request call:

https://github.com/db2dinosaur/db2-rest-python-samples/blob/master/driveTLSGetDepartments.py

And here’s the (truncated in the middle) output:

Conclusions

More fun with Python! Now we can drive DB2 for z/OS, consume data and work with stored procedures, using the Requests library. The simple power of Python combined with the stored procedures supplied with DB2 for z/OS to support administrative processes will help any budding DevOps advocate rapidly deliver real value.

 

Access all of James Gill’s Native REST API blogs here.