REST API reference

The z/TPF system supports various REST APIs that client applications can use to access z/TPF resources.

For each API, the following information is provided:

URL: The URL that identifies the resources on the z/TPF system.
Method: The HTTP method that is applied to the URL.
Description: The description about what the API is used for.
API documentation: The implementation details about the API. Most REST APIs are provided with an OpenAPI descriptor that describes the implementation details of the API. You can use the Swagger Editor to view an OpenAPI descriptor. If an OpenAPI descriptor is not provided, see the referenced topic for the details about the API.

The APIs are grouped by the resources on the z/TPF system. The following resources are available for client applications to call in REST:

REST APIs for service management

REST APIs are provided for you to display, add, and remove services on a z/TPF HTTP server.

Table 1. REST APIs for service management
URL	Method	Description	API documentation
/tpf/srvcmgmt/service	GET	Displays a list of services on the HTTP server.	/sys/tpf_pbfiles/tpf-fdes/tpfsrvcmgmt.swagger.json
/tpf/srvcmgmt/service?filename=`file.swagger.json`	POST	Adds a service to the HTTP server.	/sys/tpf_pbfiles/tpf-fdes/tpfsrvcmgmt.swagger.json
/tpf/srvcmgmt/service?filename=`file.swagger.json`	DELETE	Deletes a service from the HTTP server.	/sys/tpf_pbfiles/tpf-fdes/tpfsrvcmgmt.swagger.json

REST provider services

REST provider support provides several APIs for any REST client to retrieve API information and manage REST services. Those APIs can provide information for OpenAPI descriptors that are loaded to the z/TPF system.

Table 2. REST provider services
URL	Method	Description	API documentation
/zosConnect/apis	GET	Retrieves a list of APIs that are loaded to the z/TPF system.	Retrieval of the API list
/zosConnect/apis/{APIname}	GET	Retrieves the details about an API.	Retrieval of the details about an API
/<apiBasePath>/api-docs	GET	Retrieves the OpenAPI descriptor for an API.	Retrieval of the OpenAPI descriptor for an API

REST services for ECB trace data

REST services are provided for you to produce ECB trace data in JSON format for the requested ECB. Before you can use the ECB Trace view in TPF Toolkit, you must deploy the REST services to your z/TPF system.

Table 3. REST services for ECB trace data
URL	Method	Description	API documentation
/tpf/tools/trace/ecb/`appl_ecb_sva`?maxItems=`number`	GET	Retrieves the ECB trace data for the ECB that has the system virtual address as `appl_ecb_sva`. The maxItems query parameter is optional, where `number` is a value in the range of 1 - 500. The default value is 500.	/sys/tpf_pbfiles/tpf-fdes/tpf_ecb_trace.swagger.json

REST services for program management

REST services are provided for you to manage loadsets through the online E-type loader.

Table 4. REST services for program management
URL	Method	Description	API documentation
/tpf/pgmmgmt/v1/loadset	POST	Load a loadset.	/sys/tpf_pbfiles/tpf-fdes/loadset.tpf.swagger.json
/tpf/pgmmgmt/v1/loadset/`loadset`	PUT	Activate or deactivate a loadset on a single processor.	/sys/tpf_pbfiles/tpf-fdes/loadset.tpf.swagger.json
/tpf/pgmmgmt/v1/loadset/`loadset`	DELETE	Delete a loadset.	/sys/tpf_pbfiles/tpf-fdes/loadset.tpf.swagger.json
/tpf/pgmmgmt/v1/loadset/`loadset`	GET	Display the status and contents of a loadset.	/sys/tpf_pbfiles/tpf-fdes/loadset.tpf.swagger.json
/tpf/pgmmgmt/v1/loadset/	GET	Display a list of all loadsets and their status.	/sys/tpf_pbfiles/tpf-fdes/loadset.tpf.swagger.json

REST services for trace log data

REST services are provided for you to produce ECB trace log files in JSON format. Before you can use the Trace Log Collection view in TPF Toolkit, you must deploy the REST services to your z/TPF system.

Table 5. REST services for trace log data
URL	Method	Description	API documentation
/tpf/tools/trace/log	POST	Starts trace log collection for an ECB.	/sys/tpf_pbfiles/tpf-fdes/tpf_ecb_trace.swagger.json
	PUT	Stops trace log collection for an ECB. This service creates a trace log file in JSON format in the trace log directory on the z/TPF file system. The trace log directory is specified in the z/TPF debugger and code coverage configuration file.
	GET	Gets a trace log file.
	DELETE	Deletes a trace log file.
/tpf/tools/trace/log/list	GET	Gets a list of all trace log files that are in the trace log directory.

Depending on the amount of code to be included in the trace, the trace log collections might be large. Therefore, you need to consider the following factors:

The z/TPF system uses 31-bit system heap to transfer trace log files. You can use the ZDTKA ALTER command with the MMES parameter specified to increase the 31-bit system heap area if needed.
When you specify the trace log directory in the z/TPF debugger and code coverage configuration file, ensure that you specify the directory on a z/TPF file system that is large enough to hold your trace log files. To change the size of a z/TPF file system, use the ZFILE mount command.

Scriptable code coverage services

z/TPF scriptable code coverage support provides REST services that collect code coverage data for your source code.

Table 6. Scriptable code coverage services
URL	Method	Description	API documentation
/tpf/tools/ccv/services	GET	Retrieves code coverage results from the z/TPF system.	/sys/tpf_pbfiles/tpf-fdes/ccv.tpf.swagger.json
	DELETE	Deletes code coverage results from the z/TPF system.
	POST	Starts the collection of code coverage data on the z/TPF system.
	PUT	Stops the collection of code coverage data on the z/TPF system, and calls the service that converts the collected data to a format that is consumable by IBM® TPF Toolkit 4.6 or later or a format that is consumable by SonarQube. If the results are in IBM format, view the results in the Code Coverage Results view, which appears by default in the TPF Code Coverage perspective in TPF Toolkit. If the results are in SonarQube format, view the results by using a SonarQube instance.
/tpf/tools/ccv/connection	GET	Checks whether the z/TPF system can connect to the host that the scriptable code coverage convert web application was deployed to.
/tpf/tools/ccv/status	GET	Checks the status of code coverage processing on the z/TPF system and Linux® on IBM Z®.
/tpf/tools/ccv/converstion/list	GET	Returns a list of file names of all formatted code coverage result files in a subdirectory of the /TPFCodCov/formatted directory on the z/TPF system.

To make scriptable code coverage services work properly for remote formatting, ensure that your web application server is active. For more information, see Installing a web application server.