Create a DB2 REST service

What you are creating

A Db2 REST service is not a separate application server. DDF listens for HTTPS (or HTTP in locked-down labs), accepts JSON, runs the bound SQL under a Db2 package, and returns JSON. One service contains a single CALL, DELETE, INSERT, SELECT, TRUNCATE, UPDATE, or WITH statement. Parameter markers in the SQL become named fields in the request body.

Creating the service builds a package in a collection and records metadata in SYSIBM.DSNSERVICE. Ownership defaults to the authorization ID that creates the service. Callers need EXECUTE on that package, plus successful authentication through HTTP basic auth, PassTicket, or client certificate as your site configures. AT-TLS usually encrypts the session.

Prerequisites

REST support must already be enabled on the subsystem: required maintenance applied, REST infrastructure objects created, and DDF started with REST services available. Confirm with your systems programmer that -DISPLAY DDF and site enablement jobs completed before you invent services.

You need authority to execute the embedded SQL and to bind a package into the target collection. Agree on the collection ID, service name, versioning policy (if enabled), description, and bind options such as isolation, EXPLAIN, OWNER, and QUALIFIER. Prepare a tested SQL statement that uses parameter markers for every client-supplied value. Do not hard-code credentials or environment-specific literals into the service SQL.

• DDF active and REST enablement complete
• Collection name and naming standards approved
• SQL statement reviewed for security and access path
• EXECUTE grant model for application roles defined
• HTTPS / AT-TLS and HTTP auth path known

Steps: create with BIND SERVICE

Put the SQL statement in a data set or in-stream DD. Submit a TSO batch job that runs IKJEFT01 and issues BIND SERVICE. Specify the collection, NAME, SQLDDNAME pointing at that DD, optional DESCRIPTION, and any bind options your shop requires. Successful completion returns return code 0 from the bind step; that is not an HTTP status code.

Keep the SQL source under change control. A service is a deployable API surface: changing the statement means rebinding or creating a new version according to your versioning rules.

1
2
3
4
5
6
7
8
9
10
11
12
13
//BINDRST EXEC PGM=IKJEFT01
//SYSTSIN  DD *
  DSN SYSTEM(DB2A)
  BIND SERVICE(SALESCOLL) NAME(GETCUST) -
       SQLDDNAME(SQLIN) DESCRIPTION('Get customer by id') -
       ISOLATION(CS) OWNER(SALESAPP)
  END
/*
//SQLIN    DD *
SELECT CUSTOMER_ID, NAME, STATUS
  FROM SALES.CUSTOMER
 WHERE CUSTOMER_ID = ?
/*

Steps: create with the createService API

Alternatively, POST JSON to the Db2ServiceManager endpoint. Set Accept and Content-Type to application/json. Required keys include requestType set to createService, sqlStmt, and serviceName. Provide the collection identifier your release expects (collection or collectionID per your documentation), optional description and version, and optional bindOption text for bind keywords.

A successful create returns HTTP 201. Use this path when automation or a REST client is the preferred deploy vehicle. The result is still a Db2 package plus DSNSERVICE metadata, just like BIND SERVICE.

1
2
3
4
5
6
7
8
{
  "requestType": "createService",
  "sqlStmt": "SELECT CUSTOMER_ID, NAME, STATUS FROM SALES.CUSTOMER WHERE CUSTOMER_ID = ?",
  "collectionID": "SALESCOLL",
  "serviceName": "GETCUST",
  "description": "Get customer by id",
  "bindOption": "ISOLATION(CS)"
}

Invoke and verify results

Discover services with the discovery API or -DISPLAY RESTSVC, then invoke your service with HTTP POST and a JSON body that supplies each parameter marker. Confirm HTTP 200 (or the documented success code), correct result fields, and SQL error mapping for bad keys or unauthorized callers.

Verify the package and DSNSERVICE row, grant EXECUTE to the application role only, and test STOP RESTSVC / START RESTSVC so operators know how to take a service offline without dropping it. FREE SERVICE (or dropService) removes the definition when you truly retire it.

1
2
3
-DISPLAY RESTSVC(*)
-STOP RESTSVC(SALESCOLL.GETCUST)
-START RESTSVC(SALESCOLL.GETCUST)

Common errors

Create failures usually mean REST is not enabled, DDF is not available, the creator lacks bind or SQL privileges, the collection is wrong, the SQL statement type is unsupported, or versioning was requested when versioning is not enabled. HTTP 4xx on create often points at JSON key names, missing required fields, or authentication.

Invoke failures commonly mean missing EXECUTE, wrong parameter names or types, STOPPED service status, TLS/auth misconfiguration, or SQLCODE failures from the embedded statement. Treat the service like any other package: check authorization, bind options, and the underlying SQL with a non-REST test when diagnosis is unclear.