Skip to content

Web Services API Concepts

The ChangeMan ZMF Web Services API is a Web-enabled messaging layer built over the ChangeMan ZMF XML Services API. It enables developers to create applications that access ZMF functionality over an intranet, an extranet, or the World Wide Web.

Web Services Message Flow Web Services Message Flow

SOAP Protocol

The Web Services API works by organizing existing ChangeMan ZMF XML Services into named classes (Web Services) and methods (functions). Inbound calls to these services and methods are wrapped in an XML-defined, open-standard messaging syntax called SOAP (Simple Object Access Protocol). The SOAP message is transmitted over an HTTP connection to a Web Services application server, such as Apache Tomcat or IBM Websphere. The application server directs messages to the appropriate ZMF Web Service, which in turn invokes a server-side Java servlet that acts as a connector to ZMF.

ZMF Connector Java Servlet

The ZMF Connector servlet strips off the SOAP wrapper, then validates the data in the request against a Web Service specification defined in a Web Services Definition Language (WSDL) file. (WSDL is also an open, XML-based standard.) If the data in the request is valid, the ZMF Connector forwards it over a TCP/IP link as a straightforward XML Services request to ChangeMan ZMF. ZMF XML Services replies are received by the ZMF Connector, encapsulated in a SOAP wrapper, then forwarded by the Web application server back to the Web client.

Thick Clients and Thin Clients

The ZMF Web Services API supports both thick and thin client types.

Thick Client

A thick client is an application in which most of the custom-coded function executes locally on the client computer. This approach is preferred when computational workload can profitably be offloaded from the server to the client; when the high bandwidth demands of a rich user interface or multimedia processing can be offloaded from the network to the client; or when security considerations demand independent processing on both sides of the connection. In these kinds of situations, a ZMF Web Services application would be coded to reside on the client and send SOAP messages via HTTP to the application server where the ZMF Web Services API is hosted. In the preceding diagram, the gold box labeled "Thick Client" shows where your Web Services code would reside in a thick-client application and illustrates the kinds of Web Services message flows involved when a thick client connects to ChangeMan ZMF.

Thin Client

A thin client is an application in which most of the custom-coded function executes on a server, with the results supplied on demand to the client computer. In a Web Services context, a thin client is often simply a Web browser, which sends a standard HTTP request to the Web application server, which invokes a custom server-side application and then serves the result to the client. In the background, the custom application sends SOAPformatted messages as needed to the ZMF Web Services API, which converts each message to XML, passes it to ZMF, receives the reply, reformats the XML reply in a SOAP wrapper, and returns it to the custom application. In the previous figure, the gold box labeled "Custom Application" shows where your Web Services code would reside in a thinclient application and illustrates the kinds of Web Services message flows involved when a thin client connects to ChangeMan ZMF.

Request/Response Cycle

Session Management

Like the ZMF XML Services transactions they are built over, ZMF Web Services transactions consist of a request message issued by the client, followed by a reply message returned by the host. However, HTML and SOAP are stateless protocols that do not automatically associate a particular reply with a particular request. It is the Web client developer’s responsibility to maintain state and session information to properly associate requests and replies.

Array Results

The SOAP protocol does not support "boxcar" chaining of multiple requests or responses in a single transaction. However, several ChangeMan ZMF XML Services build in a workaround for this problem in tasks such as searches or requests for parameter lists, which typically return a large number of identically formatted XML strings. The relevant XML Service packages such results in an array, with the number of elements in the array noted in the first array element. The ZMF Web Services API accepts such array results and passes them to the Web client in a single response message.

Supported ChangeMan ZMF Functions

Developer Functions

All ZMF developer functions are accessible through the ZMF Web Services API. These include package creation, freeze, approval, promotion, revert, and backout; component checkout and checkin; package and component search functions; impact analysis and audit; user notifications; and others. In addition, the Web Services API supports SERNET file and dataset services for basic file manipulations such as download and upload, as well as retrieval of DDname allocations and performing ISPF file tailoring.

Administrator Functions

ZMF administrator functions are supported in read-only mode. For example, you can retrieve a list of package parameters using the Web Services API, but you cannot change those parameters.

ERO

The Web Services API does not support ZMF Enterprise Release Option (ERO) functions.