Storage management services

The storage management services are an application programming interface (API), which is implemented through industry standard Representational State Transfer (REST) services. The storage management services provide a programming interface for system storage elements.

Table 1 lists the operations that the storage management services provide.

Table 1. Operations provided through the storage management services.
Operation	HTTP method and URI path¹
Get a list of ACS routines	`GET /zosmf/storage/rest/<version>/acsroutines`
Get an ACS routine	`GET /zosmf/storage/rest/<version>/acsroutines/<con-type>`
Get base configuration properties	`GET /zosmf/storage/rest/<version>/baseconfig`
Get a list of storage groups	`GET /zosmf/storage/rest/<version>/storagegroups`
Get a storage group definition	`GET /zosmf/storage/rest/<version>/storagegroups/<stg-name>`
Get a list of volumes	`GET /zosmf/storage/rest/<version>/volumes`
Get a volume definition	`GET /zosmf/storage/rest/<version>/volumes/<volume-ser>`
Get a list of data classes	`GET /zosmf/storage/rest/<version>/dataclasses`
Get a data class definition	`GET /zosmf/storage/rest/<version>/dataclasses/<dc-name>`
Get a list of storage classes	`GET /zosmf/storage/rest/<version>/storageclasses`
Get a storage class definition	`GET /zosmf/storage/rest/<version>/storageclasses/<sc-name>`
Get a list of management classes	`GET /zosmf/storage/rest/<version>/managementclasses`
Get a management class definition	`GET /zosmf/storage/rest/<version>/managementclasses/<mc-name>`
Define a volume list to a storage group	`POST /zosmf/storage/rest/<version>/storagegroups/<stg-name>/volumes`
Validate an SCDS	`PUT /zosmf/storage/rest/<version>/cds/<scds-name>`
Activate an SCDS	`POST /zosmf/storage/rest/<version>/cds/<scds-name>`
Get an SCDS activation result	`GET /zosmf/storage/rest/<version>/cds/<scds-name>`

Notes:

The valid value for <version> is v1.

Using the Swagger interface

You can use the Swagger interface to display information about the storage management services REST APIs. For more information, see Using the Swagger interface.

Required authorizations

The client must be authenticated. For information about client authentication in z/OSMF, see Authenticating to z/OSMF.

Common HTTP Request Headers

Accept-Encoding

This request header indicates which forms of content encoding (compression types) are acceptable to the client program. The actual encoding that is used by the server is indicated in the Content-Encoding response header. The supported encoding method is gzip, which is specified as the following value:

Accept-Encoding: gzip

The response content is compressed with this method, if the content exceeds 4096 bytes.

Common HTTP Response Headers

Content-Encoding

This response header indicates which encoding method was used to decompress the media-type that was specified in the Accept-Encoding header. The supported encoding method is gzip, which is specified as the following value:

Content-Encoding: gzip

The response content is compressed with this method, if the content exceeds 4096 bytes.

Error handling

For errors that occur during the processing of a request, the API returns an appropriate HTTP status code to the calling client. An error is indicated with a 4nn code or a 5nn code.

In addition, some errors might also include a returned JSON object that contains a message that describes the error. You can use this information to diagnose the error or provide it to IBM® Support, if required.

The following HTTP status codes are valid:

HTTP 200 OK: The request was processed successfully.
HTTP 200 Created: The request was created successfully.
HTTP 204 (No content): The request was completed successfully.
HTTP 400 Bad request: The request cannot be processed because it contains a syntax error or an incorrect parameter.
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 the client did not authenticate to z/OSMF using a valid WWW-Authenticate header.
HTTP 403 Forbidden: The server received the request but rejected it.
HTTP 404 Not found: The requested resource does not exist.
HTTP 405 Method not allowed: The requested resource is a valid resource, but an incorrect method was used to submit the request. For example, the request used the POST method when the GET method was expected.
HTTP 408 Request timed out: The client did not produce a request within the allowed time. The request can be submitted again.
HTTP 500 Server error: The server encountered an error when it processed the request. For a more specific indication of the error, check the response for a reason code.
HTTP 501 Not implemented: The request specifies an HTTP method that is not recognized by the server.
HTTP 503 Service unavailable: The request cannot be completed by the server because of a temporary condition. If the response contains a Retry-After header, check the suggested wait time. Otherwise, the requester can treat the response as an HTTP 500 response.

Some errors might also include a returned JSON object that contains a message that describes the error. You can use this information to diagnose the error or provide it to IBM Support, if required. For the contents of the error report document, see Error reporting categories.

Error logging

Errors from the storage management 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 z/OSMF log files in IBM z/OS® Management Facility Configuration Guide.