DB2 Native REST API – Getting Started

Introduction

With DB2 for z/OS customers expanding their business presence into the mobile client world, solution developers are seeking more efficient ways to leverage existing data and business logic to support this.

The REST (Representative State Transfer) native API implemented in DB2 is a light weight interface using HTTP POST / GET request handling to drive SQL and stored procedures, with the result sets being returned in JSON (Java Script Object Notation) format.

Having read about this new feature in DB2 V12, we were keen to try it out and find out how it all worked. REST has been around for a number of years and DB2 has supported it from a client point of view since V8 (SOAPHTTPxx functions), and with the z/OS Connect product, has been able to participate as a server.

The z/OS Connect solution is based on Websphere Liberty Server, and provides a means for z/OS solutions (DB2, IMS, CICS and MQ) to provide a public REST interface to business function and application data.

This was positioned as a temporary solution until such time as the supported products could provide native support.

Enter DB2 V12, with headline support for a native REST API as part of DDF. Unfortunately, it was not mature enough to make it into the QPP program, and was therefore not delivered on GA.

It did, however, arrive with maintenance (continuous delivery!) at the end of 2016, having been back ported to V11 and released in November.

This is the first blog in a sequence that covers:

• Installation and configuration of the feature
• Creating and Dropping Services
• A sample DB2 REST application
• Some thoughts on security
• BLOBs and CLOBs

Installation

The REST API has been delivered to DB2 V11 and V12 through the maintenance stream, and to support clarity on when function has become available (DB2 V11 support was delivered in two parts), IBM have an informational APAR running which holds the current position – see II14827:

https://www-01.ibm.com/support/docview.wss?uid=isg1II14827

At the time of writing (early January 2017), the following maintenance is required:

Note that whilst deploying the maintenance delivers the capability, there are additional actions that need to be taken to enable it – and these are not documented in the ++HOLD. The key points are covered below, and by the time you read this, should be covered in the IBM online DB2 documentation as well.

Actions

1. Before rolling your maintenance out, create the new REST configuration control table SYSIBM.DSNSERVICE. This is delivered in (untailored) xxx.SDSNSAMP(DSNTIJRS). You will need to copy the job from your SMP/E target SDSNSAMP and tailor it for your intended environment. This ensures that the control table exists when you restart DB2 as part of your maintenance delivery, and REST will then be enabled.
2. Before rolling your maintenance out, create a new RACF DSNR class profile to cover REST API connection security. This takes the form:ssid.RESTand is like the other DSNR profiles – if the userid attempting a connection has READ auth, the connection may proceed, otherwise it is rejected. Again, having this in place ahead of the maintenance roll ensures that REST will function following the maintenance restart.
3. If you intend using REST for real world data, enable the DDF SSL connection, and route all REST requests this way. We will discuss security in more (and possibly tedious) detail in a future post, but suffice to say, as REST depends on HTTP POST / GET plain text processing, it is a good idea to encrypt the stream from prying eyes, even if it is just to protect the user authentication process.

Verification

So, you’ve created the control table and defined the DSNR ssid.REST and got READ auth permitted to your userid. You’ve applied and rolled out the maintenance and you’ve restarted DB2. Did it work?
The quickest way to verify this is to point the web browser of your choice (we’ve used IE and Chrome) at your DB2 DDF address:

https://my.db2.ip.addr:port/services/

If it’s all working, you will be prompted for a userid and password to make the connection with, and then you should see something like this:

Note that if you’re using Internet Explorer, it doesn’t really understand JSON very well and assumes that it’s a file to be downloaded. We used Google Chrome to look at this output with the free JSON Formatter extension (by Callum Locke) from the Chrome Store.

Next
In the next blog, DB2 Native REST API – Creating Services, we’ll look at how we created (and dropped) services, making them available to REST / DDF.

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