Introduction
One of the things that we frequently want to do is to perform a quick check of the REST service that we’ve just created. In the previous blogs we’ve seen how we can do this with PHP and Java, but why can’t we just use a command line tool?
Well, we can. Curl, or cURL (“see URL” – get it?) is a command line tool (and library) which support transferring data using a variety of protocols. Given our focus is on REST, we’ll be looking at HTTP and HTTPS.
Curl is available from its open source home:
It is bundled with most Linux distributions, but can be downloaded for Linux or Windows from the web site.
Making a Simple REST Request With curl
In its most simple form, curl can return the contents of a URL – e.g.
What have we actually done when issuing this command? Well, like web browsers, we’ve issued a GET request for the supplied URL, without any additional request headers or data / parameters.
The DB2 for z/OS REST API responds to three different HTTP(S) request types:
- GET – request a resource from the server
- HEAD – like a GE request, but only return response headers
- POST – submit data to a resource on a server
Returning the Service Profile
To get a service profile, issue a GET (as your web browser does) against the service URL – e.g.
Note that we’ve used the “-u userid:password” option. This creates the “Authorization” header with the userid and password in base64 format. This is required to authenticate with DB2 for z/OS and RACF, unless a client certificate is used (see below).
Here’s the output:
Driving the Service
If we want to drive the service, we need to POST to it. We can do this by setting the request type (-X option) and supplying the “Content-Type” header:
Note that options flags are case sensitive – “-h” = help, “-H” = header.
Here’s the output:
AT-TLS, SECPORT, HTTPS and Client Certificates
In previous posts we have also worked with the encrypted DB2 for z/OS SECPORT, and it would be useful to see how to do this with curl as well.
Making a Simple HTTPS Request
If you are using a commercial certificate supplier, chances are you already have their CA (certificate authority) certificate installed in your operating system. To make your simple HTTPS request just requires adapting the URL to the correct protocol and port. In the example below, https instead of http and – in our case 5041 (SECPORT) instead of 5040 (PORT in the DSNJU003 DDF config):
If you don’t have your suppliers CA certificate installed, or like us, you’re using your own RACF service to create the certificates (see blog #6 for details), then you’ll need to tell curl where to find the custom CA certificate. To do this, use the –cacert option:
Like this:
Using Client Certificate Authentication
If you’re using client certificates with SECPORT to provide authentication to DB2, rather than plain text userid and password, then you will additionally need to supply this information as well. Note that client certificates need to provide both the public face (the certificate and public key data) and the private (the private key information).
To do this we supply the certificate filename via –cert option and the private key data filename with –key. The file type for both defaults to PEM, but can be overridden to DER or ENG using –cert-type and –key-type.
Passing Data on the Request
The examples so far have focused on the GetDepartments service call used in previous blog posts to return a list of Departments from the sample DEPT table. Now we want to extend to include data – parameters – with our request. To do this, we’ll use the GetEmployeesByDepartment service, which returns a list of employees and the manager for a department from the sample EMP table. The service takes two parameters:
- dept – the three character department ID, and
- mgr – the six character employee ID of the manager
To pass this into the request requires us to format the data into JSON, i.e.
In this example, we’ve set mgr = 000010 (Christine Haas) and dept = “A00” (Spiffy Computer Service Div). On a Linux box, we can supply the data like this:
However, Windows command line doesn’t understand single quotes, so we end up having to escape all of the double-quotes required:
So, to make the curl request using the AT-TLS DB2 SECPORT and HTTPS from a Windows PC
Here’s the same request using the regular DB2 DDF port and basic (plain text) userid and password:
Both requests produce the following results:
Conclusions
The curl command line tool is extremely useful for providing a way to verify a new REST service from the command line of the client box. The fact that curl is bundled on most Linux distributions, and is a short download away for Windows machines should make it part of the verification toolset of all DB2 for z/OS REST developers.
Access all of James Gill’s Native REST API blogs here.