Using z/OS Connect REST APIs
z/OS® Connect provides a set of RESTful APIs that you can use to discover services, check service status, start or stop services, get statistics, and other operations.
About this task
You can use z/OS Connect REST APIs from a client running in a web, mobile, or cloud environment.
Procedure
- Discover services in the z/OS Connect configuration.
Sample HTTP GET request:
https://host:port/zosConnect/services
Sample JSON payload returned:
{ zosConnectServices: [ { ServiceName: "recordOpsCreate" ServiceDescription: "Creates a new record" ServiceProvider: "SAMPLE-1.0" ServiceURL: "https://host:port/zosConnect/services/recordOpsCreate" }, { ServiceName: "recordOpsDelete" ServiceDescription: "Deletes an existing record" ServiceProvider: "SAMPLE-1.0" ServiceURL: "https://host:port/zosConnect/services/recordOpsDelete" } ] }
- Retrieve configuration data for a service. Sample HTTP GET request:
https://host:port/zosConnect/services/recordOpsCreate
The output is returned in two parts: the first part contains the z/OS Connect configuration parameters and the second part has the configuration returned by the service provider implementation. The following is a sample of JSON payload that was returned:
{ zosConnect: { serviceName: "recordOpsCreate" serviceDescription: "Creates a new record" serviceProvider: "SAMPLE-1.0" serviceURL: "https://host:port/zosConnect/services/recordOpsCreate" serviceInvokeURL: "https://host:port/zosConnect/services/recordOpsCreate?action=invoke" dataXformProvider: "jsonByte-1.0" }, recordOpsCreate: { targetProgram: "CREATREC" timeout: "300ms" } }
- Retrieve service status. Sample HTTP GET request:
https://host:port/zosConnect/services/recordOpsCreate?action=status
Sample JSON payload returned.
{ zosConnect: { serviceName: "recordOpsCreate" serviceDescription: "Creates a new record" serviceProvider: "SAMPLE-1.0" serviceURL: "https://host:port/zosConnect/services/recordOpsCreate" serviceInvokeURL: "https://host:port/zosConnect/services/recordOpsCreate?action=invoke" dataXformProvider: "jsonByte-1.0" serviceStatus: "Started" } }
- Retrieve request schema. Sample HTTP GET request:
https://host:port/zosConnect/services/recordOpsCreate?action=getRequestSchema
Sample JSON payload returned.
{ <Request schema as returned by the data configured data transformer> }
- Retrieve response schema. Sample HTTP GET request:
https://host:port/zosConnect/services/recordOpsCreate?action=getResponseSchema
Sample JSON payload returned.
{ <Request schema as returned by the data configured data transformer> }
- Retrieve statistics.
Statistics include z/OS Connect data for a service such as
InvokeRequestCount
, and aTimeOfRegistrationWithZosConnect
, along with any other statistics returned by the service provider using thegetStatistics()
SPI implementation in the provider. Statistics for a particular service can be retrieved through a/zosConnect/operation
or anaction= request
call./zosConnect/operations
requests offer more flexibility because the product can retrieve statistics for all services. If the authorization interceptor is enabled, then the product returns statistics for only those services that the user can request. See the documentation about z/OS Connect security for more details.Sample HTTP GET request to return statistics using
action=getStatistics
:https://host:port/zosConnect/services/recordOpsCreate?action=getStatistics
Sample JSON payload returned.
{ recordOpsCreate: { ServiceProvider: "SAMPLE-1.0" InvokeRequestCount: 100 TimeOfRegistrationWithZosConnect: "xxx-xx-xx xx:xx:xx:xxx xxx" ServiceStatistics: { <JSON name value pairs showing statistical information the service returned> } } }
- Retrieving statistics for a service can be also accomplished
using the
zosConnect/operations/getStatistics
REST API.Information returned includes statistics for all services that the current user can request.
Sample HTTP GET request using
/zosConnect/operation/getStatistics
:https://host:port/zosConnect/operations/getStatistics
Sample JSON payload returned.
{ zosConnectStatistics: [ { recordOpsCreate: { ServiceProvider: "SAMPLE-1.0" InvokeRequestCount: 100 TimeOfRegistrationWithZosConnect: "xxx-xx-xx xx:xx:xx:xxx xxx" ServiceStatistics: { <JSON name value pairs showing statistical information the service returned> } } }, { recordOpsDelete: { ServiceProvider: "SAMPLE-1.0" InvokeRequestCount: 100 TimeOfRegistrationWithZosConnect: "xxx-xx-xx xx:xx:xx:xxx xxx" ServiceStatistics: { <JSON name value pairs showing statistical information the service returned> } } } ] }
If there are no services registered with z/OS Connect, the output resembles:
{ zosConnectStatistics:[] }
- Retrieve statistics for all services that are defined for
a specific service provider using the zosConnect/operations/getStatistics
REST API.
Sample HTTP GET request:
https://host:port/zosConnect/operations/getStatistics?provider=SAMPLE-1.0
Sample format/output:
{ recordOpsCreate: { ServiceProvider: "SAMPLE-1.0" InvokeRequestCount: 100 TimeOfRegistrationWithZosConnect: "xxx-xx-xx xx:xx:xx:xxx xxx" ServiceStatistics: { .. JSON name value pairs showing statistical information the service returned. } } }
- Retrieve statistics for a single service using the zosConnect/operations/getStatistics?service=<service
name> REST API. This operation is equivalent to specifying
action=getStatistics
on a service. HTTP GET request on:https://host:port/zosConnect/operations/getStatistics?service=recordOpsCreate
Sample JSON payload returned:
{ recordOpsCreate: { ServiceProvider: "SAMPLE-1.0" InvokeRequestCount: 100 TimeOfRegistrationWithZosConnect: "xxx-xx-xx xx:xx:xx:xxx xxx" ServiceStatistics: { <JSON name value pairs showing statistical information the service returned> } } }
- Stop z/OS Connect services by using an HTTP POST or PUT
request with
action=stop
, or start the services by using HTTP POST or PUT with theaction=start
query string.Stop and start actions do not require a payload. If one is provided, it is ignored. A user can retrieve the status of a z/OS Connect service using HTTP GET on the service name with the
action=status
query string to retrieve the service status. If the authorization interceptor provided by z/OS Connect is enabled, the user that is requesting the status or state change must be in the operator or administrator group required for the service. For each, the Service Provider SPI is called by z/OS Connect to notify it that these actions have been requested. The method names that are in the SPI for this arestop(
),start()
, andstatus()
.Note: z/OS Connect does not persist any state that is related to the service and instead delegates this to the service provider.The service provider can send responses other than stop or start. z/OS Connect allows for a custom status to be returned.
Stop a service sample using HTTP POST or PUT:
https://host:port/zosConnect/services/recordOpsCreate?action=stop
Sample JSON payload returned:
{ zosConnect: { serviceName: "recordOpsCreate" serviceDescription: "Creates a new record" serviceProvider: "SAMPLE-1.0" serviceURL: "https://host:port/zosConnect/services/recordOpsCreate" serviceInvokeURL: "https://host:port/zosConnect/services/recordOpsCreate?action=invoke" dataXformProvider: "jsonByte-1.0" serviceStatus: "Stopped" } }
- Start a service sample using HTTP POST or PUT:
https://host:port/zosConnect/services/recordOpsCreate?action=start
Sample JSON payload returned:
{ zosConnect: { serviceName: "recordOpsCreate" serviceDescription: "Creates a new record" serviceProvider: "SAMPLE-1.0" serviceURL: "https://host:port/zosConnect/services/recordOpsCreate" serviceInvokeURL: "https://host:port/zosConnect/services/recordOpsCreate?action=invoke" dataXformProvider: "jsonByte-1.0" serviceStatus: "Started" } }
- Invoke services using the z/OS Connect query string:
action=invoke
, which runs theinvoke()
method of the Service Provider SPI implementation.The sample in this step runs the invoke method for the service named
recordOpsCreate
and passes a JSON object payload in the request body.The z/OS Connect invoke method supports an input payload in JSON object form for this request. In the code example, it is assumed that z/OS Connect looked up the Service Provider and identified a service reference for the service called
SAMPLE-1.0
. There is also a data transformation reference in the z/OS Connect service definition with a provider calledjsonByte-1.0
. With this in place, when the invoke method of the service provider gets control and it calls thegetBytes()
method, the data transformation implementation gets control and converts the request payload from JSON to a byte array and returns it to the service provider.If the URL that the invoke action request came in with contains query parameters, these parameters along with other HTTP request information are passed to the service provider using the
com.ibm.wsspi.zos.connect.HttpZosConnectRequest
SPI interface provided by z/OS Connect. Interceptors processed for actions or operations also receive HTTP request information through the same object.Another invocation style that is supported by z/OS Connect provides a means to define a user-defined URI as the
invokeURI
in the z/OS Connect service definition. With this style, the HTTP request does not have to containzosConnect/services
and can instead be a user-defined string.When this style is employed, z/OS Connect supports use of other HTTP methods, such as GET, PUT, POST, and DELETE. Requests arriving with this URI, regardless of the HTTP method employed, pass through z/OS Connect interceptors and are passed to the
invoke()
method of the service provider.Sample using HTTP POST or PUT:
https://host:port/zosConnect/services/recordOpsCreate?action=invoke { <JSON object passed in for the service invocation> }
Sample JSON payload returned:
{ <JSON object returned from the service invocation> }