How it works: CMCI REST API
The CICS management client interface (CMCI) provides a REST application programming interface (API) for system management clients such as IBM® CICS Explorer®. The CMCI REST API can also be used in an automated process, by leveraging the Ansible® IBM z/OS CICS collection.
The CMCI REST API is supported through HTTP. The client initiates an HTTP request to the CMCI. If the interface determines that the request is valid, it constructs a CICSPlex® SM API command or, in the case of a stand-alone CICS region, a CICS system command. After running the command, the CMCI creates an HTTP response. If the request is successful, this takes the form of an HTTP 200 (OK) response and an XML feed containing a result set, which it passes back to the client. If the request is not successful, the response consists of a non-OK HTTP response code with details of the failure.
The format for CMCI HTTP requests and responses is based on the HTTP/1.1 protocol. See The HTTP protocol for more information about this protocol.
How to make CMCI HTTP requests
A CMCI request takes the form of an HTTP header followed by a URI (Universal Resource Identifier) and, where appropriate, an XML body containing details of any changes to be made to CICS or CICSPlex SM resources.
- DELETE
- Removes resources from the CICSPlex SM data repository, removes resources from the CICS system definition data set (CSD), or discards installed resources.
- GET
- Retrieves information about resources in the CICSPlex SM data repository, retrieves information about resources on the CSD, or retrieves information about installed resources.
- POST
- Creates resources on the CICSPlex SM data repository or resources in the CSD.
- PUT
- Updates existing resources in the CICSPlex SM data repository, updates existing resources in the CSD , or sets attributes and performs actions on installed resources. Also performs actions on CICSPlex SM and CSD resources.
The URI includes the name of a CICS or CICSPlex SM resource, and specifies a series of parameters that refine the scope and nature of the query to identify one or more instances of the specified resource. In a GET request, the URI also specifies whether the API retains or discards a set of results. If the API retains the results, a new request can act on the retained results without having to repeat the retrieval operation. You can also use subsequent requests to page through the retained results selecting one or more records at a time.
POST and PUT requests include an XML body. In a PUT request the body contains either details of the changes to be made to resource attributes, or the action to be performed on the targeted resources. In a POST request, the body incorporates the attribute values you want to give to the new resource instance.
GET and DELETE requests do not require an XML body. If additional parameters are required for a DELETE request, those parameters must be included in the URI and can optionally be added to the XML body.
Find out more
CMCI REST API programming reference gives your details on the DELETE, GET, POST, and PUT methods, CMCI resource names, CMCI XML body elements, diagnostic aids, and so on.