DB2 REST and modern APIs

Native REST services

Native REST services are a DDF feature. You expose one static SQL statement—or a CALL—as an HTTP resource. Clients send JSON; Db2 runs the bound service package and returns JSON. Metadata lives in SYSIBM.DSNSERVICE. The URL shape is typically /services/collection/serviceName with an optional version segment.

Allowed SQL per service is a single CALL, DELETE, INSERT, SELECT, TRUNCATE, UPDATE, or WITH statement. Parameter markers become JSON fields. Result sets become JSON arrays. REST work can be zIIP-eligible like other DDF threads, which is one reason shops adopt it for lightweight read APIs.

JSON and HTTP

JSON is the body format for create, discover, and invoke. Content-Type is application/json. HTTP POST is the common verb for invocation and management; some metadata operations use GET depending on the endpoint. AT-TLS (or equivalent TLS termination) should protect the port—REST without encryption is a lab toy, not a production pattern.

1
2
3
4
5
POST https://db2t.example.com:443/services/SYSIBMSERVICE/deptByLoc
Authorization: Basic ...
Content-Type: application/json
 
{"LOCATION": "LONDON"}

Client headers such as Db2-Client-ApplName and Db2-Client-WrkStnName populate client special registers for accounting—useful when many APIs share one technical user.

REST service manager

The REST service manager endpoint is DB2ServiceManager. You POST a JSON document whose requestType selects the action—most importantly createService and drop-style operations. Required create keys include requestType, sqlStmt, and serviceName. Optional keys cover collectionID, description, version, owner, qualifier, and other bind options. Several JSON keys are case-sensitive; copy IBM’s spelling exactly.

1
2
3
4
5
6
7
8
9
{
  "requestType": "createService",
  "sqlStmt": "SELECT DEPTNO, DEPTNAME FROM DEPARTMENT WHERE LOCATION = ?",
  "collectionID": "SYSIBMSERVICE",
  "serviceName": "deptByLoc",
  "description": "Department by location",
  "owner": "DB2GRP1",
  "qualifier": "HR"
}

REST service discovery and invocation

REST service discovery uses DB2ServiceDiscover. A discovery POST returns serviceName, collection, version, and serviceURL so mobile and middleware teams do not hard-code every path after a rename. Operators still query SYSIBM.DSNSERVICE when they need catalog truth.

REST service invocation is the business call: POST JSON to the service URL. Markers map to request fields; SELECT responses include result-set rows; change statements return status and row-count style information. Keep services narrow—one statement, one clear contract—so OpenAPI docs stay honest.

REST service lifecycle

Availability commands matter in change windows: -STOP RESTSVC blocks new discover/invoke traffic for a name or version while leaving the definition in place; -START RESTSVC reopens it; -DISPLAY RESTSVC shows status. Decommission with FREE SERVICE (DSN) or the manager drop API when the service should disappear entirely.

1
2
3
-DISPLAY RESTSVC(SYSIBMSERVICE.deptByLoc)
-STOP RESTSVC(SYSIBMSERVICE.deptByLoc)
-START RESTSVC(SYSIBMSERVICE.deptByLoc)

BIND SERVICE and CREATE SERVICE API

BIND SERVICE

BIND SERVICE(collection) is a DSN subcommand under IKJEFT01. NAME is the service name. SQLDDNAME points at the SQL text. SQLENCODING names the CCSID of that text (1047 is a common EBCDIC choice). Ordinary package options—OWNER, QUALIFIER, ISOLATION, EXPLAIN—apply. Collections group services the way BIND PACKAGE collections group programs; SYSIBMSERVICE is a common default.

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
//CR8SRVC EXEC PGM=IKJEFT01,DYNAMNBR=20
//STEPLIB  DD DISP=SHR,DSN=DSN.DB2T.SDSNEXIT
//         DD DISP=SHR,DSN=DSN.DB2T.SDSNLOAD
//DSNSTMT  DD DISP=SHR,DSN=SYSADM.SERVICE.SQL(SELECT1)
//SYSTSPRT DD SYSOUT=*
//SYSTSIN  DD *
  DSN SYSTEM(DB2T)
  BIND SERVICE(SYSIBMSERVICE) -
       NAME("deptByLoc") -
       SQLDDNAME(DSNSTMT) -
       SQLENCODING(1047) -
       DESCRIPTION('Department names for a location') -
       QUALIFIER(HR) OWNER(DB2GRP1)
  END
/*

CREATE SERVICE API

The CREATE SERVICE API is createService on DB2ServiceManager—the same outcome as BIND SERVICE for teams that automate from pipelines without JCL. Versioning (when enabled) stores a VARCHAR(64) version; default behavior centers on V1. Invoke a specific version in the URL; stop or free one version without necessarily touching others.

z/OS Connect, OpenAPI, and API management

z/OS Connect is an API gateway on z/OS. It can front native REST (and other z/OS backends), present a developer portal, and enforce enterprise policies. OpenAPI (Swagger) documents describe paths, schemas, and status codes so TypeScript, Java, and Python clients generate stubs safely. API management adds rate limits, API keys, routing, and lifecycle governance across environments.

Native REST does not require Connect. Use Connect (or another gateway) when multiple systems must look like one catalog, when product owners demand OpenAPI-first delivery, or when security teams insist on a single edge for quotas and threat protection. Keep the SQL service thin; put orchestration in the gateway or a dedicated service layer, not in a giant WITH statement nobody can test.

REST authentication and authorization

REST authentication commonly uses:

• HTTP basic authentication — user/password or RACF PassTicket
• Client certificate authentication — certificate mapped through SAF / trusted context patterns

When both are present, Db2 may authenticate the certificate, establish a trusted connection, then switch user with the basic credentials. REST authorization is still SQL: callers need EXECUTE on the service package (and whatever table privileges the package’s bind rules require). Do not put SYSADM in every mobile app header—create least-privilege IDs per API consumer.

REST monitoring

REST monitoring combines Db2 and edge signals. On Db2: DISPLAY RESTSVC, DDF thread displays, accounting classes for the service packages, and SQLCODE patterns on failed invokes. On the edge: gateway latency, 4xx/5xx rates, and auth failures. Profile tables and RLF still apply to abusive clients—REST is not exempt from governors.

For distributed tracing across cloud apps and Db2, see OpenTelemetry support on Db2 for z/OS (inbound W3C context on REST among other attach paths). REST headers can carry trace parent information when the whole stack is instrumented.

Explain It Like I'm Five

Native REST is a mailbox on the Db2 house. You write one SQL homework sheet (BIND SERVICE or createService) and nail it to the mailbox. A phone app drops a JSON note through the slot. Db2 runs the homework and slides a JSON answer back. Discovery is asking the receptionist for the mailbox list. z/OS Connect is a fancy lobby with a tourist map (OpenAPI). STOP RESTSVC hangs a “closed” sign; FREE SERVICE takes the mailbox down.

Exercises

1. Write BIND SERVICE JCL for a SELECT with one parameter marker. Name collection and NAME.
2. Convert that definition into createService JSON. Mark case-sensitive keys.
3. Sketch an OpenAPI path object for the invoke URL and request body.
4. Explain when you would deploy native REST alone versus native REST behind z/OS Connect.
5. List authentication methods and the GRANT still required after a successful login.