DB2 Native REST API – Versioning and Control
Introduction
The DB2 for z/OS REST API has been available on V11 and V12 for a while now and has continued to evolve through IBMs continuous delivery maintenance strategy.
With the arrival of APAR PI98649 (V12 PTF UI58425, V11 PTF UI58431), the functionality has been extended to include commands to control the availability of services and the addition of a service versioning system.
Versioning
REST service versioning has been introduced to support multiple versions of a service being active and usable at the same time. This means that if we need to modify an existing service, we can do this under a new version without replacing the existing service which may be in use by other clients.
The first version of a service becomes the default version when it is created. The default version can always be accessed by the traditional service URL – i.e.
host:port/services/collid/service
Non-default versions are referenced using the same service name, but with the addition of the specific version to be used:
host:port/services/collid/service/version
e.g.
https://s0w1.zpdt.local:2050/services/GILLJSRV/GetDepartments/V2
This allows the service to evolve over time, without risking disenfranchising users of older versions.
Enabling
Versioning is enabled by installing PI98649 on ALL members of the data sharing group, and then tailoring and running job DSNTIJR2 (in SMP/E target.SDSNSAMP). This adds additional columns to the SYSIBM.DSNSERVICE REST catalog table.
Existing services cannot be versioned without dropping and redefining them.
Using – Creating Services
Once enabled, all new services are versioned. If a version id (VARCHAR(64)) is specified it is used, otherwise REST applies ‘V1’. This version id is used for the service and the supporting package. It can be specified in the service creation parameters – e.g. Python:
e.g. BIND SERVICE:
Note that in BIND SERVICE, VERSION does not allow quotes. Note also that we have to use double quotes in BIND and GRANT to reference mixed case service names.
How to Change the Default Version
Stop.
Since this blog was originally written in 2018, IBM have released maintenance (PH34544 – May 2021) to manage the default service version. This is covered in a new blog post here. The following method is interesting from a historical point of view, but the REBIND…RESTSERVICEDEFAULT(YES) method is the recommended approach now.
Before you do this, remember that the default version is in place to support the first users of your service. If you change the default version, you will potentially stop these users from working. Before doing this, make sure that you understand the implications.
We did this as an exercise to allow us to tidy up some now unused versions of a service as you cannot issue FREE SERVICE against the default version:
Whilst not documented, the default version can be changed by modifying the contents of the REST catalog table SYSIBM.DSNSERVICE.
We chose to stop the services that were being changed to make them unavailable:
-STOP RESTSVC(‘GILLJSRV.GetDepartments.’)
Then update the SYSIBM.DSNSERVICE table to make the default service V3:
Restart the services and check that the change is applied:
We were then able to FREE the original default version:
New Commands
The new commands are to help manage the availability of services, and to provide the flexibility to withdraw and reinstate them:
-DISPLAY RESTSVC(serviceRef)
-START RESTSVC(serviceRef)
-STOP RESTSVC(serviceRef)
Note that the default scope of the commands is member (in a data sharing group) and that you need system privileges to run them – specifically one of:
- System DBADM
- SYSOPR
- SYSCTRL
- SYSADM
Most folks use mixed case names for their services and you should be aware that to specify these correctly, the whole serviceRef should be enclosed in single quotes. E.g.
GILLJSRV.GetDepartments = fail (GetDepartments will be folded to upper case
GILLJSRV.’GetDepartments’ = fail (invalid character in the service name)
GILLJSRV.”GetDepartments” = fail (same again)
‘GILLJ*.*’ = fail (collection name must be fully qualified, or as rest service name *.*)
‘GILLJSRV.GetDepartments’ = okay
‘GetDepartments’ = okay (for SYSIBMSERVICE.GetDepartments)
And with versioning:
‘GILLJSRV.GetDepartments.(V2)’ = okay but expects a version = “(V2)”, so not found
‘GILLJSRV.GetDepartments’.V2 = fail
‘GILLJSRV.GetDepartments.V2’ = okay
Note also that care should be used when deciding where to issue these commands. The DB2I Commands (option 7) panel folds all of the input to upper case before issuing it. If issuing from SDSF:
/-DISPLAY RESTSVC(‘GILLJSRV.GetDepartments’) -> folds command to upper case
/ and then entering the command on the following panel works
The DSN command processor (in TSO or batch) and IFI command interface work correctly.
-DISPLAY RESTSVC
The command shows the status of services. The V12 manual entry is here:
E.g.
Note that the service status (started or stopped) is also correctly reported in the DB2ServiceDiscover output – e.g.
https://s0w1.zpdt.local:2050/services/
-STOP RESTSVC
The command stops the service or services specified and rejects attempts to run (POST) or query (GET) them. The V12 manual entry is here:
Note that unless you specify a specify a specific version, all versions of a service are stopped.
E.g.
Note V1 is flagged with status STOPREJ* – the “*” indicates that this is the default version (used if a version is not specified with HTTP GET or POST).
Services that have been stopped return HTTP status code 503 (Service Unavailable) when run (POST) or queried (GET), and the service discovery reflects their availability:
https://s0w1.zpdt.local:2050/services/
The set status is maintained across DB2 restarts, as with other entities.
-START RESTSVC
This command restarts stopped services and makes them available to respond to HTTP GET and POST commands. The V12 manual entry can be found here:
Again, like the -STOP command, unless you specify a specific version, all versions or the named service are started.
E.g.
Bonus Items
Some other items have been updated by APAR PI98649:
- JSON key names have been changed for some DB2ServiceDiscover fields to align them with the service detail (call for a specific service). See the APAR text for details. This is probably only of interest if you’re writing your own DB2 REST tool.
- UNION/INTERSECT/EXCEPT queries now show the correct column names in the returned result set
- Service creation now reports all of the bind options
- The BIND SERVICE command no longer frees the SQLSTMT DD when it has finished. This is to allow the same SQLSTMT DD to be used in multiple BIND SERVICE statements in the same job step. The documentation states that the DD is only freed at step end, which could make this a nuisance if used in a TSO session…
- Distributed client PRDID and accounting strings are changed to reflect the client connection type and HTTP command:
- PRDID:
- HTP01010 – HTTP/REST request
- HTS01010 – HTTPS/REST request
- Client accounting string (CHAR(5)):
- ‘GET ‘ – service discover
- ‘PUT ‘ – service run
- A few other things have been “fixed” as well – see the APAR text – here
- PRDID:
Conclusions
The handling of mixed case service names in the new commands feels a little clunky, as it doesn’t follow the syntax used in other commands and SQL statements.
IBM are, however, continuing to enhance the REST API as part of their commitment to continuous delivery. There are a lot of useful new elements introduced in this APAR which will help with the management of REST services provided by DB2.
Access all of James Gill’s Native REST API blogs here.
Leave a Reply