EntireX RESTful Services

Issue 4, 2014

Download pdf

EntireX leverages Software AG’s common Web services stack 

Why is the REST architecture style so popular? Explore the reasons and discover how EntireX supports REST through an explicit example that implements RESTful Web services for calling mainframe programs through an EntireX RPC server. Although this article is not intended to compare REST vs. SOAP, it explains some of the basic differences and why you might want to use one over the other.

Why use REST?

Representational State Transfer (REST) is an architectural style developed by the W3C open standards body to be used in parallel with HTTP 1.1. Although it competes with the likes of SOAP for architecting and conducting Web service interfaces, REST has no official standard (unlike SOAP-based Web services which adhere to an RFC “protocol”). Instead, REST Web services are described by an implementation “style” using broad RFC standards like HTTP, URI, XML and JSON.

Web services APIs that adhere to a REST style are called RESTful. HTTP-based RESTful APIs are characterized by their use of Uniform Resource Identifier (URI) that allows hypertext link references.

The success of REST over SOAP rests from the desire to simplify building connections between client-server components by using a loosely coupled style while having effective run-time performance attributes. Essentially, it is easier to create and modify a RESTful URI to access different resources than to use SOAP and a WSDL. Typically, SOAP requires specific knowledge of the XML schema specification, thus driving many developers to use a SOAP toolkit to form requests and parse the results.

What is WSSTACK?

Software AG’s Web Services Stack (WSSTACK) is used by many of our products to provision Web service APIs in common ways using common Software AG tools. The WSSTACK:

  • Supports both SOAP and RESTful styles
  • Operates within Apache, WebSphere® or WebLogic® application servers
  • Provisions EntireX for deploying add-on services for emulating RPC clients and servers
  • Installs from Software AG Installer using  the Infrastructure and Designer trees (EntireX tree contains EntireX Web services runtime) 
  • Includes stand-alone documentation available here
     

EntireX REST example

If you’d like to follow along with this example, we recommend you use the standard WS STACK run-time delivered and configured with Software AG Installer.

The following example demonstrates how EntireX uses REST to call a mainframe program. The information steps you through the generation, deployment and testing of EntireX services using the EntireX Workbench (Software AG Designer with EntireX plug-in) in conjunction with the standard WS STACK run-time.

  1. Create XML mapping from example.idl
    Use one of the common EntireX example artifacts, as shown in Figure 1, and start from the IDL file context menu. Click the “Generate XML/SOAP Mapping“ option. Next, clear the “Namespace URI“  field, choose “Element Mapping,“ then click on “Generate“ and save the mapping file (XMM).


    Figure 1: EntireX IDL example artifact
     
  2. Deploy mapping
    From the XMM file context menu, click on “Generate Web Service …“, select “Deploy service”, unselect “Use defaults”, select “Set connection and security…”, as shown in Figure 2. Then click “Next”.

     
    Figure 2: Generate EntireX Web service.

    Now configure the mapping file to generate the EntireX Web service using an existing Broker ID and RPC Server Address as shown in Figure 3 then click “Next”.

    Figure 3: Configure mapping file

    Now enter the service URL and select the desired programs, as shown in Figure 4. Click “Next”.



    Figure 4: Enter service URL

    Now choose the desired location to deploy the EntireX XML Service as shown in Figure 5.


    Figure 5: Choose desired location

    This step automatically deploys the EntireX XML service when using the common Tomcat® Web service platform. Click “Finish” to complete this step and you are now ready to test calling a mainframe program from a browser using the mapped input parameters in the URI.
     
  3.  Call either example service from the browser
    You can now build out this URI reference for calling this mainframe program from a local HTTP client or use a domain name (replacing localhost) to call it remotely as shown in Figure 6.

    Figure 6: Calling the mainframe program from a local HTTP client or use a domain name

Note that the operation parameter (%2B) in the CALC URI in Figure 6 is in UUENCODE for this text parameter.
 

Limitations of REST

Although increasingly popular, REST may not always be the preferred approach. There are currently some specific limitations with the EntireX-generated RESTful Web services that may sway you from REST in favor of SOAP-based Web services:

  • The request document cannot contain groups, arrays, other nested elements or attributes
  • Elements cannot be namespace-qualified
  • Only services that accept requests in plain XML can be called (that means no JSON)
     

Summary

With EntireX, exposing important mainframe programs through a RESTful API is a convenient and flexible way to provide different kinds of consumers with data formatted in a standard way. REST helps meet critical integration requirements using a simple yet efficient URI method.