Developers

Omnis Technical Note TNWS0003 December 2014

Getting Started with REST Web Services, Tomcat and Swagger UI

For Omnis Studio 6.1 or above
by Rod Cooper, Omnis Engineering

This tech note describes how to setup a Tomcat Web Server with Swagger UI for use with the Omnis Studio REST Web Services Server. It discusses how to create your own Web Service from Omnis code and uses the following example library:
restfuldemo.zip (for Studio 10.22 or above)
restfuldemo-2019.zip (pre-Studio 10.22)

For information about implementing a Web Services Client interface see the tech note: TNWS0002.

Creating your own Web Services

Omnis Studio 6.1 introduced a new Web Server plug-in which allows you to expose the code in your Omnis applications and provide them as Web Services for any clients to consume. The interface for the web services you can create and provide to clients is exposed as an API or set of APIs. The new functionality allows Omnis REST APIs (or ORAs) to be fully defined using a “Swagger” definition, which is the most widely used standard for defining REST APIs.

Omnis REST APIs are visible in the Studio Browser as children of the library node beneath the Web Service Server node (the same as previous implementations of Web Services based on WSDL files). Each ORA is shown a separate node icon in the tree, and various options or actions are shown as hyperlinks when an ORA is selected. The Swagger definition can be viewed using the IDE browser hyperlinks for the ORA.

To create a Web Service or Omnis REST API you need to set some properties of a remote task and add some REST methods. The remote task class has two new properties to allow you to setup the Web Service: $restful must be set to kTrue to make the remote task RESTful, and $restfulapiname is the name of the RESTful API.

When a remote task is RESTful, the remote task has a group of objects (named $objs as usual) which are the URIs exposed by the remote task to clients. A URI must have one or more components starting with /. Parameter place-holders can be included as component two or later as {paramName} where paramName is unique (case-insensitive) in the URI. URIs are like other class objects in classes with instances, in that they can have their own methods. There are some special methods supported for URIs, called HTTP methods. These correspond directly to the HTTP protocol methods used by a RESTful API, and they are: $delete, $get, $head, $options, $patch, $post, $put.

HTTP methods of a URI have some special features and properties. The first parameter for all HTTP methods must be named pHeaders, and defined as a Field reference. This references a row which contains the HTTP headers received in the RESTful request from the server. The row has a column for each HTTP header.

For methods which accept content with the request ($patch, $post, $put) the second parameter must be named pContent, which is a Field reference to the content received in the request. When you create a new HTTP method, Omnis automatically creates the parameters pHeaders and pContent, and it also automatically adds a character parameter for each parameter place-holder in the URI.

The Omnis method editor has additional features for a RESTful remote task. There are new menu items that allow you to insert a new URI, delete or rename a URI, and insert a new HTTP method. In addition, when the currently selected method is an HTTP method, the variables panel has two additional tabs: RESTful and RESTful notes that let you set the input type, output type and HTTP response codes, as well as the notes about the method which is written to the swagger definition.

The Configuration dialog for the Omnis App Server allows two new properties to be configured: the RESTful URL which is the base URL used to call Omnis RESTful Web Services, and RESTful connection which controls how the Omnis RESTful Web Server plugin connects to Omnis.

Requirements

• Windows Vista or above.
• Omnis Studio dev kit serialised with a Web Services Plugin serial number.
• Java Development kit (JDK) or Java SE Runtime environment (JRE) version 7. Visit http://www.oracle.com/technetwork/java/javase/downloads/index.html to download and install as required.
• Environment User variable OMNISJVM or OMNISJVM64 set to the path of jvm.dll within your java installation (ie. c:\program files\java\jre1.8.0_25\bin\server\jvm.dll)

Setting up a Tomcat web server for use with RESTful Web Services

1. Download Tomcat 8.0 or above 32-bit binary core distribution for Windows from http://tomcat.apache.org
2. Extract the downloaded zip file and move the folder apache-tomcat-8.0.15 to a convenient location, i.e. c:\program files\apache-tomcat-8.0.15.
3. Tomcat requires the following two environment system variables to be declared. These can be configured via System| Advanced System Settings of the Windows Control Panel.
   - CATALINA_HOME which needs to be set to the location of your Tomcat folder, i.e. c:\program files\apache-tomcat-8.0.15.
   - JAVA_HOME which needs to be set to the location of your Java JDK or JRE installation, i.e. c:\program files\java\jdk1.8.0_25.
4. Copy the omnisrestservlet folder from the clientserver\server folder of your Omnis Studio Development tree to the webapps folder of your Tomcat tree.

Installing Swagger UI

Swagger UI allows you to view and test your Omnis RESTful web service in a web browser.

1. Download the latest release of swagger ui from https://github.com/swagger-api/swagger-ui/releases using the green 'Latest Release' button on the left hand side of the web page.
2. In the Apache Tomcat WebApps folder, create a new folder called 'swagger-ui'
3. Now copy the contents of the downloaded swagger-ui\dist folder into the WebApps\swagger-ui folder.

Starting Tomcat

After completing the steps above, Tomcat can now be started by running startup.bat located in the bin folder of your Tomcat tree. If already running, run shutdown.bat first and then restart or if running an alternative web server such as IIS then this must also be stopped first.

Using Omnis Dev as a RESTful web server

To use the Tomcat server you have just installed as a RESTful web server you need to set the ‘Server port’, ‘RESTful URL’ and ‘RESTful Connection’ fields in the server configuration dialog as shown below, and replace 99.99.99.99 with your IP Address. To open this dialog, select the Web Service Server node in the Studio Browser and click on the ‘Server Configuration’ hyperlink.

RESTful Server example library

Open the RESTful example library swaggerdemo.lbs and note the service ‘wizard’ displays beneath the Web Service Server node in the browser. This is the value as assigned to the restfulapiname property of the remote task rtWizard.

The ‘Show Method List’ hyperlink shows the HTTP methods in the remote task belonging to the URI ‘data’.

The example itself creates a sqlite database from a comma separated text file which can be queried and updated via the RESTful web service.

To use, open the window wWizard, drag the supplied text file phonelist.txt onto the open window and follow the steps below to access via the RESTful web service.

Calling the RESTful Service from Swagger UI

Swagger UI uses a URI to call the RESTful web service, clicking on the Resource Listing hyperlink in the Web Service Server shows the URI at the top of the swagger data.

Open Swagger UI in a web browser by visiting 'http://99.99.99.99:8080/swagger-ui/index.html' where 99.99.99.99 is your IP Address. Enter the URI as shown above, press Explore to view the Omnis RESTful web service and use the Show/Hide hyperlink to view methods.

Press ‘Try it out!’ on GET and the HTTP method ‘$get’ of the URI ‘/data’ in the remote task rtWizard returns a list of contacts from the sqlite database.

To insert a new contact using PUT, click on the model schema box to ‘set as parameter value’ and enter values such as those below and press ‘Try it Out’.

To view the newly inserted row on the server together with any existing data, test the form ‘jsWizard’ in the swaggerdemo library.

Calling the RESTful Service from Omnis Studio

Omnis Studio 6.1 includes a HTTP Web Worker object for calling RESTful web services. The example library swaggerclient.lbs is provided and shows how this can be used to call the above RESTful web service from a client machine, rather than using Swagger UI.

To use the client demo, open the window wRestfulClient, enter the URI http://99.99.99.99:8080/omnisrestservlet/ws/1234/api/swaggerdemo/wizard/data where 99.99.99.99 is the IP Address of your Tomcat server.

Select HTTPGet and press ‘Test’ to retrieve data from the server or HTTPPut to enter content and send to the server for insertion.