Software services instance services

The software services instance services are application programming interfaces (APIs), which are implemented through industry standard Representational State Transfer (REST) services. These services allow the caller to create and manage software services instances in the software services registry.

For information about cloud provisioning, including a description of the roles, see Cloud provisioning services.

The software services registry contains a list of the software on z/OS that has been registered as being provisioned, typically through the use of software services templates, although provisioning can be done manually. It is maintained in the z/OSMF data repository and has a sysplex-wide scope.

Table 1 lists the operations that the software services instance services provide.

Table 1. z/OSMF software services instance services: operations summary
Operation name	HTTP method and URI path
Create a software services instance	`POST /zosmf/provisioning/rest/<version>/scr`
Get the contents of a software services instance	`GET /zosmf/provisioning/rest/<version>/scr/<object-id>`
Get the variables for a software services instance	`GET /zosmf/provisioning/rest/<version>/scr/<object-id>/variables`
Get key-value variables for a software services instance	`GET /zosmf/provisioning/rest/<version>/scr/<object-id>/key-value-variables`
List the software services instances	`GET /zosmf/provisioning/rest/<version>/scr`
Perform an action against a software services instance	`POST /zosmf/provisioning/rest/<version>/scr/<object-id>/actions/<action>`
Delete a software services instance	`DELETE /zosmf/provisioning/rest/<version>/scr/<object-id>`
Update a software services instance	`PUT /zosmf/provisioning/rest/<version>/scr/<object-id>`
Update variables in a software services instance	`PUT /zosmf/provisioning/rest/version/scr/object-id/variables`
Get the response for an action performed against a software services instance	`GET /zosmf/provisioning/rest/<version>/scr/<object-id>/actions/<action-id>`
List the responses for actions performed against a software services instance	`GET /zosmf/provisioning/rest/<version>/scr/<object-id>/actions`
Delete the response for an action performed against a software services instance	`DELETE /zosmf/provisioning/rest/<version>/scr/<object-id>/actions/<action-id>`

Authorization requirements

Use of the software services instance services API requires the client to be authenticated. For information about client authentication in z/OSMF, see Authenticating to z/OSMF.

In addition, the user’s z/OS user ID may need access to other resources, including those that define roles such as the domain administrator. The specific requirements for each software services instance service are described in the topic for that service. For an overview of the security requirements for cloud provisioning roles, see Authorization requirements. For details, see IBM z/OS Management Facility Configuration Guide.

Error response content

For the 4nn HTTP error status codes, additional diagnostic information beyond the HTTP status code is provided in the response body for the request. This information is provided in the form of a JSON object containing the following fields:

Table 2. Response from a request failure
Field	Type	Description
httpStatus	Integer	HTTP status code.
requestMethod	String	HTTP request method.
requestUri	String	HTTP request URI.
messageID	String	Message identifier for the error.
messageText	String	Message text describing the error.
additionalInfo	String	Additional information describing the error.
debug	String	Debug information about for the error.

Error logging

Errors from the software services instance services are logged in the z/OSMF log. You can use this information to diagnose the problem or provide it to IBM Support, if required. For information about working with z/OSMF log files, see IBM z/OS Management Facility Configuration Guide.

HTTP status codes

The following HTTP status codes are valid:

HTTP 200 OK: The request succeeded. A response body is provided, which contains the results of the request.
HTTP 201 Created: The request succeeded and resulted in the creation of an object.
HTTP 202 Accepted: The request was successfully validated and is performed asynchronously.
HTTP 204 No content: The request succeeded, but no content is available to be returned.
HTTP 400 Bad request: The request contained incorrect parameters.
HTTP 401 Unauthorized: The request cannot be processed because the client is not authorized. This status is returned if the request contained an incorrect user ID or password, or both. Or, the client did not authenticate to z/OSMF by using a valid WWW-Authenticate header.
HTTP 404 Not found: The requested resource does not exist.
HTTP 409 Request conflict: The request cannot be processed because of conflict in the request, such as an edit conflict between multiple updates.