Start of change

REST services versioning

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.

Consider using Db2 REST service versioning if any of the following applies to you:

  • You need to keep the existing version of a REST service available while you create another version.
  • You want your applications and consumers of a REST service to use a specific version of a REST service.
  • You have a REST service with versions using different SQL statements, different inputs and output parameters, and bind options.
  • You want Db2 REST service discovery and invocation package authorizations to be common across multiple versions of a REST service.
  • You want to specify a version string on Db2 REST services.

REST services created prior to enabling REST versioning support are version-less, and have the following attributes:

  • A version-less REST service definition is the default service version for the <collection id>.<service name>.
  • No other versions of a version-less <collection id>.<service name> can be created.
  • A version-less REST service will have an empty-string (“”) value for the VERSION column in both SYSPACKAGE and DSNSERVICES tables.
  • Version-less REST services will continue to be referenced using the default version URI: /services/<collection id>/<service name>

REST services created after enabling the REST versioning support will always have an assigned version, and have following attributes:

  • The initial Db2 REST service that is created for a given <collection id>.<service name> is set as the default service version.
  • The default service version of a Db2 REST service can be changed using the REBIND PACKAGE (DSN) subcommand with the RESTSERVICEDEFAULT bind option.
  • The default service version can be referenced using either the explicit version URI: /services/<collection id>/<service name>/<version> or the default service version URI: /services/<collection id>/<service name>
  • Any REST service created without a user specified version will be created using the default version value, V1.
  • A valid REST service version has one to 64 characters, each of which is an uppercase letter, lowercase letter, numerals (0-9), the underscore (“_”) character, the dash (“-“) character, the period (“.”) character, the ampersand (“@”) character, the pound sign (“#”) character, or the dollar sign (“$”) character.
  • The default service version of a REST service cannot be dropped or freed when other versions of that service exist.
  • One or more versions of a REST service can exist at any point in time at the current server, but only one version of a REST service is considered the default version. When you first create a REST service, that initial version is considered the default version of the REST service.

Enabling REST services versioning support

Db2 REST service versioning support is enabled by running sample installation job DSNTIJR2. If you are using Db2 data sharing, the required maintenance must be installed and active on all members of the data sharing group. For more information, see the instructions and comments provided in the sample job and Enabling Db2 REST services.

REST service URI format with versioning

A new Db2 REST service URI format is needed to support the use, discovery, and invocation of versioned REST services.

The basic Db2 REST service URI format is /services/<collection-id>/<service-name>. If the <collection id> portion is omitted, then the default “SYSIBMSERVICE” collection ID is used. This basic Db2 REST service URI will continue to work for all existing Db2 REST services and will be fully supported even after the Db2 REST services versioning support is enabled.

Once the Db2 REST services versioning support is enabled, an additional Db2 REST URI format will be available for versioned REST services. The new URI format will support the version identifier in the following format: /services/<collection-id>/<service-name>/<version-id>

With this change, the valid Db2 REST service URI variations and mappings can be done in three ways.

Specified Variables URI Format Explanation
Service Name /services/<service-name> SYSIBMSERVICE, the default collection ID and the default service version of REST service <service-name> is referenced.
Collection and service name

/services/<collection-id>/<service-name>

 The default service version of the REST service <collection-id>/<service-name> is referenced.
Collection, service name, and version /services/<collection-id>/<service-name>/<version-id> The fully qualified REST service and version is referenced.

The default version for a REST service is the first REST service created for the given <collection-id>/<service-name>. A later version of the REST service can be selected as the default using the DSN REBIND PACKAGE subcommand with the RESTSERVICEDEFAULT bind option. The default version can only be dropped or freed when there are no other versions.

Example use of versioning

The Db2 REST service, MyServices.createCustomer, is created using the default version V1, and the SQL statement:

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

Using the Db2 REST service manager API, the default version V1 of the MyServices.createCustomer service could be created by issuing a POST request to the createService API with the following HTTP request body:

{
 "requestType": "createService",
 "sqlStmt": "INSERT INTO CUSTOMER (FNAME, LNAME) VALUES(:firstName, :lastName)",
 "collectionID": "MyServices",
 "serviceName": "createCustomer",
 "description": "Create a new customer profile entry.",
}

Because this is the first service with the name MyServices.createCustomer, this version of the service is the default version. The service could be invoked using the default version URI of /services/MyServices/createCustomer, or by using the version specific URI of /services/MyServices/createCustomer/V1.

A new version of the MyServices.createCustomer service is needed to include the customer’s e-mail address. The new version of the MyServices.createCustomer is created with "V2" specified as the version and the SQL statement:

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

Using the Db2 REST service manager API, version V2 of the MyServices.createCustomer service could be created by issuing a POST request to the createService API with the following HTTP request body:

{
 "requestType": "createService",
 "sqlStmt": "INSERT INTO CUSTOMER (FNAME, LNAME, EMAIL) VALUES(:firstName, :lastName, :emailAddress)",
 "collectionID": "MyServices",
 "serviceName": "createCustomer",
 "description": "Create a new customer profile entry with customer name and email.",
 "version": "V2"
}

The V2 version of MyServices.createCustomer service is invoked 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.

Later, a new V3 version of the MyServices.createCustomer service is needed so that the CUSTNUM (customer number) generated column value can be returned to the caller 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))

Using the Db2 REST service manager API, version V3 of the MyServices.createCustomer service could be created by issuing a POST request to the createService API with the following HTTP request body:

{
 "requestType": "createService",
 "sqlStmt": "SELECT CUSTNUM AS :customerAcctNum FROM 
             FINAL TABLE (INSERT INTO CUSTOMER (FNAME, LNAME, EMAIL)
             VALUES(:firstName, :lastName, :emailAddress))",
 "collectionID": "MyServices",
 "serviceName": "createCustomer",
 "description": "Create a new customer profile entry with customer name and email, returning the new customer number.",
 "version": "V3"
}

The new V3 version of MyServices.createCustomer service is invoked by using the version specific URI of /services/MyServices/createCustomer/V3, and shares the same Db2 package authorizations as V1 and V2.

End of change