Administering services with the administration interface

The administration interface for services is available in paths under /zosConnect/services.

zosConnect-2.0 Applies to zosConnect-2.0.

Most administration tasks are supported by the RESTful administration interface.

IBM® z/OS® Connect supports V1.2.0 of the RESTful administration interface. This version includes new and enhanced methods and operations that are not available in earlier versions, duplicating some non-RESTful administration functions to provide a more natural RESTful interface. A Swagger document that describes the RESTful administration interface for IBM z/OS Connect is available on the URI /zosConnect/api-docs.

Administration interface supported operations

Table 1 lists the methods and administrative tasks that are supported by the RESTful administration interface.

Table 1. Methods and administrative tasks supported by the RESTful administration interface
Method	Tasks supported by the RESTful administration interface	Enhancements
GET	Get a list of services	None
	Get details of a service	v1.1.0, v1.2.0
	Get the status of a service	v1.1.0
	Get the request schema of a service	v1.1.0
	Get the response schema of a service	v1.1.0
POST	Deploy a service	v1.1.0
PUT	Update a service	v1.1.0
PUT	Change the status of a service	v1.1.0
DELETE	Delete a service	None

Table 2 lists the methods and administrative tasks from V1.0.0 that are supported. Some administrative tasks are supported only in the non-RESTful administration interface, some only in the RESTful administration interface, and some are supported in both.

Table 2. V1.0.0 methods and tasks supported in the administration interface
Method	Administration tasks supported	Comments
GET	Get a list of services
	Get details of a service
	Get the status of a service	Supported in both the RESTful administration interface and the non-RESTful administration interface, but with a different request URI and query string.
	Get the request schema of a service	Supported in both the RESTful administration interface and the non-RESTful administration interface, but with a different request URI and query string.
	Get the response schema of a service	Supported in both the RESTful administration interface and the non-RESTful administration interface, but with a different request URI and query string.
	Get the statistics of a service	Supported only in the non-RESTful administration interface.
	Get the statistics for multiple services	Supported only in the non-RESTful administration interface.
POST	Change the status of a service

Important:

The zosconnect_services element must be added to the server.xml configuration file, even if no attributes are specified. In this case, the attributes are set to default values. If the zosconnect_services element is not added, a BAQR7070E error message is generated when the administration interface is called. For more information, see Sub elements.

Notes for all calls

When a service name is required for a call, if the service name contains forward slashes, they must be escaped by using %2F in these calls. For example, if the service name is MyService/v1, it must be provided as MyService%2Fv1.
All successful calls return HTTP status code 200 unless otherwise specified.
Any call that uses an HTTP method with a URI not mentioned in these topics returns an error 405 Method Not Allowed.
If an error occurs during request processing, an appropriate HTTP status code and the following JSON are returned:
```
{
       "errorMessage": "{message}",
       "errorDetails": "{details}"
}
```
errorDetails is optional and is returned only for some error scenarios.