Creating a Db2 REST service

You can use the Db2 REST service manager API, or createService API, to create a new user-defined service if you have the required authority. You can also issue the BIND SERVICE subcommand to create a new REST service.

Before you begin

Before you can create a service, you must apply APARs and create database objects that are required by the services. For instructions, see Enabling Db2 REST services.

When you create a service, Db2 identifies you or the authorization ID that you use as the default owner of the service. Therefore, you must have the required privileges to create a service and bind the associated package into a collection. For example, you must be authorized to execute the SQL statement that is embedded in the service. See BIND SERVICE (DSN) for information about required authorization.

Restriction: Data Studio provides no support for creating or deploying Db2 REST services.

• To create a service, issue an HTTP or HTTPS POST request through a REST client with the following URI:

  POST https://<host>:<port>/services/DB2ServiceManager

• Set the HTTP header Accept and Content-Type fields to application/json for the request.
• Optional: Set any Db2 client information related HTTP header fields with values that will be assigned to the Db2 client information special registers. For more information, see Management of REST service client information.
• Specify the create service parameters using JSON format key/value pairs in the HTTP body for the request. The requestType, sqlStmt, collection, serviceName, description, and version JSON keys are case sensitive. General service create bind option keys are case insensitive. The requestType, sqlStmt, and serviceName parameters are required. To use the version create service parameter, REST service versioning must be enabled. Specify the create service HTTP body content:

  {
   "requestType": "createService",
   "sqlStmt": "<sqlStatement>",
   "collectionID": "<serviceCollectionID>",
   "serviceName": "<serviceName>",
   "description": "<serviceDescription>",
   "version": "<versionIdentifier>",
   "<bindOption>": "<bindOptionValue>",
  ...
   "<bindOption>": "<bindOptionValue>"
  }
  

  where

  • createService indicates that you request to create a new service.
  • <sqlStatement> is the SQL statement that you include in the new service. For each new service, you can embed a single CALL, DELETE, INSERT, SELECT, TRUNCATE, UPDATE, or WITH SQL statement. When you create the service, Db2 also binds a package that is used to invoke the service.

    Db2 adds a new row in the user-defined SYSIBM.DSNSERVICE catalog table for the service and saves the bound package in the directory. Db2 also sets the HOSTLANG column in the SYSIBM.SYSPACKAGE and SYSIBM.SYSPACKCOPY tables to 'R' to mark the package for the REST API.

  • <serviceCollectionID> is the collection identifier of the package that is associated with the new service. The serviceCollectionID property is optional. If you specify <serviceCollectionID>, Db2 names the package in the form of collectionID.serviceName. Otherwise, Db2 uses the default form of SYSIBMSERVICE.serviceName.
  • <serviceName> is the name of the new service that you create.
  • <serviceDescription> is a brief description of the new service. The serviceDescription property is optional. If provided, Db2 stores the value in the DESCRIPTION column of the SYSIBM.DSNSERVICE catalog table.
  • <versionIdentifier> is an optional version identifier for the service being created. This is only valid if REST service versioning support is enabled.
  • <bindOption> is the option that you specify for binding the package that is associated with the new service. The bindOption property is optional. All bind options supported by the BIND SERVICE subcommand, except DESCRIPTION, NAME, SQLDDNAME, SQLENCODING, and VERSION, apply to the createService API. The createService API uses the serviceName, description, and version parameters, instead of the NAME, DESCRIPTION, and VERSION bind options of the BIND SERVICE subcommand. See BIND SERVICE (DSN) for supported bind options. See BIND and REBIND options for packages, plans, and services for details about the bind options.

POST https://host:port/services/DB2ServiceManager

Accept:application/json
Content-Type:application/json
Db2-Client-ApplName:Customer Service
Db2-Client-WrkStnName:CS Laptop-47

{
 "requestType": "createService",
 "sqlStmt": "SELECT DEPTNAME FROM DSN8B10.DEPT WHERE LOCATION = :LOCATION",
 "collectionID": "SYSIBMSERVICE",
 "serviceName": "simpleSelect1",
 "description": "Select department name based on location.",
 "owner": "DB2GRP1",
 "qualifier": "USRT002"
}

{
 "StatusCode":201,
 "StatusDescription":"DB2 Rest Service simpleSelect1 was created successfully.",
 "URL": "http://<host>:<port>/services/SYSIBMSERVICE/simpleSelect1/V1"
 "StatusOptions": {
  "Applied":[
    {
     "ACTION": "ADD"
   },
    {
     "VALIDATE": "RUN"
   },
    {
     "EXPLAIN": "NO"
   },
    {
     "ISOLATION": "CS"
   },
    {
     "RELEASE": "COMMIT"
   },
    {
     "OWNER": "DB2GRP1"
   },
    {
     "QUALIFIER": "USRT002"
   },
    {
     "APREUSE": ""
   },
    {
     "APCOMPARE": ""
   },
    {
     "BUSTIMESENSITIVE": "YES"
   },
    {
     "SYSTIMESENSITIVE": "YES"
   },
    {
     "ARCHIVESENSITIVE": "YES"
   },
    {
     "APPLCOMPAT": "V12R1M500"
   },
    {
     "DESCSTAT": "YES"
   },
    {
     "SQLERROR": "NOPACKAGE"
   },
    {
     "CURRENTDATA": "NO"
   },
    {
     "DEGREE": "1"
   },
    {
     "NODEFER": "PREPARE"
   },
    {
     "REOPT": "NONE"
   },
    {
     "IMMEDWRITE": "NO"
   },
    {
     "DBPROTOCOL": "DRDA"
   },
    {
     "OPTHINT": ""
   },
    {
     "ENCODING": "UNICODE(01208)"
   },
    {
     "CONCURRENTACCESSRESOLUTION": ""
   },
    {
     "PATH": ""
   },
    {
     "QUERYACCELERATION": ""
   },
    {
     "GETACCELARCHIVE": ""
   },
    {
     "ACCELERATOR": ""
   },
}