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.![End of change](../../deltaend.gif)
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 subcommand (DSN) for information about required authorization.
Restriction:
IBM® Data Studio provides no support for creating or deploying
Db2 REST services.
![End of change](../../deltaend.gif)
Procedure
-
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. The maximum length is 128 bytes.
If <serviceCollectionID> is a delimited identifier, the following characters are accepted: If <serviceName> is a delimited identifier, it can contain following characters: uppercase letters (A–Z
), lowercase letters (a–z
), numerals (0–9
), underscore (_
), at sign (@
), pound sign (#
), and dollar sign ($
).
- <serviceName> is the name of the new service that you create. The maximum length is 128 bytes.
If <serviceName> is a delimited identifier, the following characters are accepted characters: uppercase letters (A–Z
), lowercase letters (a–z
), numerals (0–9
), underscore (_
), at sign (@
), pound sign (#
), and dollar sign ($
).
- <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. The maximum length is 64 characters.
If <versionIdentifier> is a delimited identifier, it can contain the following characters: If <versionIdentifier> is a delimited identifier, the following characters are accepted: uppercase letters (A–Z
), lowercase letters (a–z
), numerals (0–9
), underscore (_
), at sign (@
), pound sign (#
), and dollar sign ($
).
- <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 subcommand (DSN) for supported bind options. See BIND and REBIND options for packages, plans, and services for details about the bind options.
Example
This example shows how to create service simpleSelect1
for OWNER DB2GRP1
and QUALIFIER USRT002
and includes setting the Db2-Client-ApplName and Db2-Client-WrkStnName HTTP request header fields to the values "Customer Service" and "CS Laptop-47", respectively. Enter the following URI to start an HTTPS POST request:
POST https://host:port/services/DB2ServiceManager
Specify the following HTTP header fields for the request:
Accept:application/json
Content-Type:application/json
Db2-Client-ApplName:Customer Service
Db2-Client-WrkStnName:CS Laptop-47
Specify the following HTTP body for the request:
{
"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"
}
Db2 returns the following response in JSON:
{
"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": ""
},
}
The response shows that service simpleSelect1
was successfully created. Since version was not specified, the version of the service created defaults to V1.If necessary, you can issue the REBIND PACKAGE command to modify the options associated with service simpleSelect1
.