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 a TimeOfRegistrationWithZosConnect, along with any other statistics returned by the service provider using the getStatistics() SPI implementation in the provider. Statistics for a particular service can be retrieved through a /zosConnect/operation or an action= 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 the action=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 are stop(), start(), and status().

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 the invoke() 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 called jsonByte-1.0. With this in place, when the invoke method of the service provider gets control and it calls the getBytes() 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 contain zosConnect/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>
}
```