This Db2 for z/OS News from the Lab blog entry was originally published on 2018-10-19.

By Tom Toomire and Emily Alameida

In Db2 11 and 12, APAR PI98649 introduces three new Db2 commands, START RESTSVC, STOP RESTSVC, and DISPLAY RESTSVC for operational control of Db2 REST services and support for versioning of REST services.

With the STOP RESTSVC command, you can stop a service during maintenance so that invocation attempts will display an unavailable reply. Once the maintenance is completed, the START RESTSVC command can be used to start the service again. The DISPLAY RESTSVC command displays the status of services, so you can see which services have been stopped.

The new Db2 REST service versioning support gives you the ability to define and use multiple versions of a REST service concurrently. Each version of a REST service can be created using a different SQL statement, different input and output parameters, and different bind options. This model provides the flexibility to create and deploy new versions of REST services to satisfy new application requirements without breaking existing applications.

Using the new REST service versioning support has the following potential advantages:

• You can keep the existing version of a REST service available while you create another version.
• Existing applications are not impacted when newer versions of a REST service are created.
• Applications and consumers of a REST service can be updated to use another version of a REST service when desired, or they can continue to use the existing version.
• Applications can be coded to use a specific version of a REST service, or they can be coded to use the default service version of a REST service.
• Each version of a REST service can be created using a different SQL statement, different input and output parameters, and different bind options.
• Db2 REST service discovery and invocation package authorizations are common across all versions of a REST service.
• Ability to create Db2 REST services with a customer specified version string.

REST service versioning example: Assume that you created a Db2 REST service, MyServices.createCustomer, using the default version “V1”, and the SQL statement:

INSERT INTO CUSTOMER (FNAME, LNAME) VALUES(:firstName, :lastName) 

Because this is the first Service with the name "MyServices.createCustomer", this version of the service is the "default version." You can invoke the service using the "default version" URI of /services/MyServices/createCustomer, or by using the version specific URI of /services/MyServices/createCustomer/V1.

Later, you decide that you need a new version of the MyServices.createCustomer service so you can also specify the customer’s e-mail address when creating a new customer account. You create the new version of the MyServices.createCustomer using version “V2”, and the SQL statement:

INSERT INTO CUSTOMER (FNAME, LNAME, EMAIL) VALUES(:firstName, :lastName, :emailAddress)

You can invoke the new “V2” version of MyServices.createCustomer service by using the version specific URI of /services/MyServices/createCustomer/V2. There is NO impact to any users of version “V1” of the MyServices.createCustomer service. In addition, the new “V2” version of MyServices.createCustomer shares all of the same package authorizations that were defined for version “V1” of the MyServices.createCustomer service.

Sometime later, you decided that you need a new “V3” version of the MyServices.createCustomer service so that the CUSTNUM (customer number) generated column value can be returned to you when creating a new customer account. The new version “V3” of the MyServices.createCustomer is created using the SQL statement:

SELECT CUSTNUM AS :customerAcctNum FROM 
FINAL TABLE (INSERT INTO CUSTOMER (FNAME, LNAME, EMAIL) VALUES(:firstName, :lastName, :emailAddress))

You can invoke the new “V3” version of MyServices.createCustomer service by using the version specific URI of /services/MyServices/createCustomer/V3. The new "V3" version of MyServices.createCustomer shares the same Db2 package authorizations as V1 and V2.

For more information about versioning, see Db2 REST services versioning.

Tom Toomire is a Senior Software Engineer at the IBM Silicon Valley Laboratory and the technical lead for the Db2 native REST service provider feature and Emily Alameida is a technical writer for Db2 for z/OS.