z/OS Compliance REST Interface

The z/OS compliance REST interface is an application programming interface (API) implemented through industry standard Representational State Transfer (REST) services. A set of REST services is provided for working with the collection of security compliance evidence on a z/OS system, as described in this topic.

The Table 1 lists the operations that the z/OS compliance REST interface services provide.

Table 1. Operations that are provided through the z/OS compliance REST interface services
Operation name	HTTP method and URI path
POST the request for compliance facts	`POST zosmf/compliance/rest/v1/facts`

Use the Swagger interface

You can use the Swagger interface to display information about the z/OS compliance REST APIs. The Swagger interface includes one section: Compliance APIs. For more information, see Using the Swagger interface.

Processing overview

This API is used to request the collection of compliance data from in-scope systems. In response, selected products and components collect and write compliance data to the SMF 1154 record type. The z/OS compliance REST interface services can be invoked by any HTTP client application that runs on the z/OS local system or a remote system. Your program (the client) initiates an HTTP request to the z/OS compliance REST interface. If the interface determines that the request is valid, it performs the requested service. After it performs the service, the z/OS compliance REST interface creates an HTTP response. If the request is successful, this response takes the form of an HTTP 2nn response. If the request is not successful, the response consists of a non-OK HTTP response code with details of the error that is provided in the form of a TEXT object.

Resource URLs

The URLs of the z/OS compliance REST interface have the format that is shown in #zOSComplianceRESTInterface__FormatResourceURLs.

https://{host}:{port} /zosmf/compliance/rest/v1

Where:

https://{host}:{port} specifies the target system address and port.
/zosmf/compliance/rest/v1 identifies the z/OS compliance REST interface.

HTTP Methods

The z/OS compliance REST interface provides the following HTTP methods: POST

POST the request for compliance facts.

Supported HTTP versions

z/OS compliance REST interface supports requests in either of the following protocols: HTTP/1.0 or HTTP/1.1.

Content Types

The data that is sent or returned by the HTTP methods has one of the following content types:

JSON Content-Type: application/json is used for sent body data. For the detailed format of each JSON object, see the description for each operation.
Plain text Content-Type: plain/text.

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 by a 4nn code or a 5nn code. For example, HTTP/1.1 400 Bad Request or HTTP/1.1 500 Internal Server Error.

The following HTTP status codes are valid:

HTTP 200 OK: Success.
HTTP 201 Created: The request is successful. As a result, a resource is created.
HTTP 202 Accepted: The request is received and is accepted for processing. However, the processing is not yet complete.
HTTP 400 Bad request: Request that contains incorrect parameters.
HTTP 500 Internal server error: Programming error.

Error logging

Errors from the z/OS compliance REST interface 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.