About Verastream Web Services

Providing a Web service to your host applications enables rapid reuse of the business logic that exists on these hosts. Web services provide reusable APIs for creating portals, Web applications, and other business solutions. And, because they are technology independent, they can run on any platform. Developers can use utilities to generate specific files to locate and consume the Web service.

Web Service Standards

Host Integrator, at model deployment, generates both a SOAP (Simple Object Access Protocol) Web service and a REST (REpresentational State Transfer) service that uses JSON (Java Script Object Notation) to call VHI procedures from a Web application.

• VHI SOAP-based Web services adhere to WS-Standards, which includes WS-Resource, WS-Security, and WS-Addressing. These standards follow a third-party specification. In most cases proper SOAP headers are generated to use these standards and it is unnecessary for you to write separate code, however some applications may not be able to consume these features for various reasons. The Web service standards are turned off by default. This setting can be changed on the Session Server Web Service Property panel in the Administrative Console.

  See a List of Web Service Specifications for a description of WS-Security, WS-Addressing, and WS-Resource.

• VHI REST services use JSON as the data carrier, and, like the SOAP-based services, runs over HTTP.

Deploying the Web Service

In VHI, after a model is deployed using the Design Tool, Web services are automatically provided by the session server as both an embedded SOAP stack and as a REST service. The embedded Web service supports all model procedures and features, including executeSQLStatement and ProcessString event handlers.

Metadata request format

• SOAP request - http://host-name:port/vhi-ws/model-or-session/model-or-pool-name?wsdl

• REST request - http://host-name:port/vhi-rs/model-or-session/model-or-pool-name?json

• Native Web-Service - http://host-name:port/models/model-or-pool-name

About Model and Environment Variables

Model variables and environment variables are an optional part of every SOAP or REST document that a client submits to a VHI Web service to invoke a Web method. Although these elements are optional, meaning that the WSDL and schema, or REST metadata, do not require them in the syntax, a given application may require them to be specified to run successfully.

After you deploy your model to the session server, you can view and test the model to see if the Web service that is created works as expected, by clicking Test on the Deployment Successful message box to open the Web Services Explorer. In the Web Services Explorer you can add, remove and view model and environment variables.

Model variables

By default, VHI creates three model variables whenever a model is created. Any user-defined model variables that you create also are listed. How these user-defined variables are used and their semantics are application-dependent.

Environment variables

VHI uses environment variables to communicate to the service how to run. For example, what server or domain to use.

Web Services Ports

Web Services deployed to the session server are set by default to run on HTTP port 9680 or HTTPS port 9681.

Using the WSDL Document

The Web Service Description Language (WSDL) document describes the interface to the Web service, the data types it uses, and the location of the service. Developers use this document to identify inputs, outputs, and methods needed to consume the Web service. Web services generation utilities use the WSDL document to create proxy objects and sample code for the services.

You can access your Web services WSDL documents here:

http://<session server>:9680/vhi-ws for a list of available WSDLs

For example:

http://<session server>:9680/vhi-ws/model/<model name>?wsdl for a non-pooled model

http://<session server>:9680/vhi-ws/session/<pool name>?wsdl for a pooled session

-or here-

https://<session server>:9681/vhi-ws for a list of available WSDLs

For example:

https://<session server>:9681/vhi-ws/model/<model name>?wsdl for a non-pooled model

https://<session server>:9681/vhi-ws/session/<pool name>?wsdl for a pooled session

Using the REST Document

Just like XML, JSON (using JavaScript syntax) is text only and thus can be read and used as data input by any programming language. However, unlike XML, JSON is very light-weight and easy to read. It is also very widely used for interchanging data on the Web.

JSON documents are an easier to use alternative to XML and follow this simple format:

{"employees":[
    {"firstName":"John", "lastName":"Doe"},
    {"firstName":"Betty", "lastName":"Brown"},
    {"firstName":"Michael", "lastName":"Jones"}
]}

You can access all available REST services for models or sessions deployed to the Host Integrator session server here:

http://<session server>:9680/vhi-rs

For example:

http://<session server>:9680/vhi-rs/model/<model name>?json for a non-pooled model

http://<session server>:9680/vhi-rs/session/<pool name>?json for a pooled session

-or here-

https://<session server>:9681/vhi-rs

For example:

https://<session server>:9681/vhi-rs/model/<model name>?json for a non-pooled model

https://<session server>:9681/vhi-rs/session/<pool name>?json for a pooled session

Example

Take a look at a REST Web application that uses the CICSAcctsDemo model to demonstrate Host Integrator's REST service. It provides an example of both a stateful and stateless procedure call.

Prerequisites

• Using the Design Tool, deploy CICSAcctsDemo to localhost. The model is located here: .../RocketSoftware/Verastream/HostIntegrator/examples/ModelSamples/CICSAcctsDemo.
• Verify that the security option is disabled in the Administrative Console. This option is disabled by default and can be found under Session Server Properties > General Properties > Security.

Metadata Web-Service

VHI provides metadata for deployed models and their procedures on a separate web service in the OpenAPI format. The OpenAPI specification describes REST APIs. Because it is language agnostic, its metadata can be used to generate code for REST clients, servers, and tests in many languages and frameworks.

The Metadata Web service runs on HTTP port 9682 and HTTPS on 9683. HTTP is disabled by default, but can be enabled by setting the environment variable VHI_NATIVE_WEBSERVICE_HTTP to true.

Certificates can be configured for HTTPS to provide secure connections. The CA certificate and private key must be in pem format. To configure certificates you must first define these environment variables:

• VHI_NATIVE_WEBSERVICE_CERT should point to the pem, the default is %VHI_ROOT%/etc/serverCertificate.pem.
• VHI_NATIVE_WEBSERVICE_KEY should point to the pem, the default is %VHI_NATIVE_WEBSERVICE_CERT%.

If your certificate and private key are in PFX format, you can use the OpenSSL command line utility or other conversion tool to convert it to standard PEM format.

For example: %VHI_ROOT%/bin/openssl pkcs12 -import -in example.p12 -out example.pem -noenc

Using Swagger UI for Web-Service Tests

Swagger UI provides an easy interface to test out the endpoints.

1. With CORS disabled, navigate to Swagger UI using HTTPS or HTTP:
   • https://localhost:9683/swagger/ui
   • http://localhost:9682/swagger/ui
2. In the search bar enter /models/CICSAcctsDemo and click Explore.
3. Select /SearchByName, and then Click Try it out.
4. Erase modVars and envVars
5. Change string to W
6. Execute and the data is returned from the web service.

Example Code Generators

You can find sample generators for Java in \HostIntegrator\examples\Generators.

Using the Java Generator

1. Optional: Retrieve the metadata from the server using curl. curl https://<url>:9683/models/<modelname> -k -o spec.json. If you are using powershell, change curl to curl.exe.

2. Install Java and Maven and add them to your path

3. Navigate to \HostIntegrator\examples\Generators\Java, where there is a sample POM, OpenAPI specification in JSON format, Windows and Unix script for your use. Copy the files to a writable location outside of the install directory. If you do not do this, the code generation will fail and throw a java.nio.file.AccessDeniedException.

4. To generate code, execute the command mvn install. This generates and compiles Java source files into the target/generated-sources/openapi folder.

5. To use a different input:

   • Open the POM.
   • In the build section, change the value of the tag <inputSpec>spec.json</inputSpec> to match the name of your spec.

6. Using your IDE, this example uses IntelliJ IDEA, open the target/generated-sources/openapi directory. When prompted, select Maven, and then Trust the project. target/generated-sources/openapi contains a README.md with the instructions on using the generated code. target/generated-sources/openapi/docs also contains a DefaultApi.md which include examples of how to use your endpoints.

Example of how to run the /SearchByName endpoint for CICSAcctsDemo:

• Windows - compile_and_run.bat
• Unix - sh compile_and_run.sh

Managing Web Service Settings

You use the Administrative Console to enable and disable all VHI Web services. In the Properties panels of the session server, model and session pool configurations you can set server-level policies as well as options for specific models and session pools.

• Server level properties set Web service configurations, including enabling HTTP or HTTPS connections and other Web service elements. You can also decide whether to make Web services available for models and pools and link to the list of all available Web services.
• Model level properties display information and options for the Web service associated with the selected model that is deployed to the session server. This is where you can override the session server values for a particular model.
• Session pool level properties contain settings to configure the Web service for a particular session pool. This is where you can override the session server properties set for the Web service and view the Web service documentation.