Omnis Technical Note TNWS0002 Updated Sept 2017

RESTful Web Services: implementing a Client

For Omnis Studio 8.1 or above

This tech note describes how you can implement a Web Services Client interface to access a third-party web service. For information about implementing a Web Service from your Omnis code see the tech note: TNWS0003.

Support for RESTful web services for client and server was introduced in Omnis Studio 6.1. There is a new external component that allows you to create a user interface to a RESTful web service, plus there is a new web server plugin that allows you to expose your Omnis code on the Omnis App Server as a Web Service. To support the processing of content returned by a web service, the JSON external component was introduced in Omnis Studio 6.1, that allows JSON based objects returned from RESTful resources to be manipulated.

What is REST? REST is the predominant architectural style being used today to consume and publish Web Services, and is seen as an alternative to other distributed-computing specifications such as SOAP. A RESTful Web Service is identified by a URI, and a client interacts with the resource via HTTP requests and responses using a fixed set of HTTP methods.

You should read the Web Services chapter in the Extending Omnis manual for full details about creating web services using the new components.

Creating a Web Services Client

The External Objects group in Omnis Studio includes a new group called OW3 Worker Objects, introduced in Studio 8.1 and superseding the Web Worker Objects group; the new worker objects do not rely on Java so this does not need to be configured to use the new worker objects. The OW3 group contains an FTPClientWorker, HTTPClientWorker, SMTPClientWorker, and IMAPClientWorker (added for 8.1.1), but to handle HTTP requests and responses to and from the Web Service you need to use the HTTPClientWorker. The Web Worker objects function in a similar manner to the DAM worker objects, although there is a simplification in the way they handle re-use of the object when a request is currently in progress: see the notes about $init.

To use the HTTP worker object, you create an Object Class which is a subclass of HTTPClientWorker. Having created a new Object class, set its $superclass property to the name of the HTTPClientWorker object by clicking on the dropdown list and selecting the object in the Select Object dialog.

Select Object

In the object class, the methods $completed and $cancelled are inherited from the superclass (the HTTP worker object) which the client worker calls with either the results of a request, or to say the request was cancelled; you can override them in the object class and add your own code. You then need to create an Object instance variable in your JavaScript remote form based on the new Object class to instantiate the object and allow you to interact with the web service by running its methods. The HTTPClientWorker object methods include: $init() that initializes the worker object so that it is ready to perform the specified HTTP request; $run() runs the worker on the main thread, while $start() runs the worker on the background thread; $cancel() cancels the worker thread; $cancelled() is called if the request is cancelled; $completed() is called when the request is completed, which returns a single row variable parameter with various columns including the content returned in the final column.

Omnis Weather: Example Web Services Client Library

We have created an example library that demonstrates the capability of Omnis to consume a RESTful web service.

Download the library from Github: https://github.com/OmnisStudio/Omnis-JSWeather (requires Studio 8.1.2 or above). Import the library into Omnis Studio 8.1.2 using the New Lib from JSON option.

Or you can download an archive RESTWEATHER.ZIP (library compatible with Omnis Studio 8.1 or above, using the OW3 worker objects and responsive forms).

To open and run the app in design mode, you'll need the latest version of Omnis Studio 8.1.x which you can download here: www.omnis.net/download

The example app is hosted on an AWS Cloud server: view the online example app

REST WEATHER

To open the app on a tablet or mobile you can enter the shortcut URL into your browser: tinyurl.com/jsweather8

REST WEATHER

Examining the RestWeather Library

The example library presents basic weather forecast information by consuming a web service provided by APIXU. To use the web service consumed in the example library, you must obtain a trial API key from APIXU and enter the key when you open the library.

To test the web service in design mode, open the example library in the Studio Browser, right click on the jsrWeather remote form and select 'Test Form' from the context menu (or use Ctrl/Cmnd-T). The $layouttype property of the remote form has been set to kLayoutTypeResponsive to make the form responsive to different screen or device sizes, which is another feature added to Studio 8.1; you can click on the 320 and 768 breakpoints to examine the layout for each.

The form tries to identify your location using the IP address returned from the remote task. Since the example library uses the free version of the API, the data on the World tab is not real-time.

When examining the code in the example library, the key methods are getWeather, getData, readCurrentData, readForecastData in jsrWeather and $completed, $returnVal in the oRest object class. The following method is in the remote form called getData – the method initializes the Web Services object, having already setup the main parameters for the $init() method, and calls the web service.

; iURI (Char) initialized as "http://api.apixu.com/v1"
; iHTTPMethod (Int) set to kOW3httpMethodGet
; iHeadersList (List)
; iContentChar (Char)
Do iHeadersList.$define(iHeaderName, iHeaderValue)
Do iHeadersList.$add("content-type", "application/json")
; call the web service
Do iRestfulObj.$init(iURI, iHTTPMethod, iHeadersList, iContentChar)
Do iRestfulObj.$run() Returns lStatus

The following is the $completed method in the oRest object in the example library:

; called by the client worker with the results
Calculate iResponse as pRow
Calculate iResponseHeaders as pRow.responseHeaders
Do OJSON.$formatjson(pRow.responseContent) Returns iReturnStr
Do OJSON.$jsontolistorrow(pRow.responseContent) Returns iJSONRow

The OJSON external component can be used to process the JSON output: see the example library for techniques you can use with OJSON, and the 'Extending Omnis' manual for more details.

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. This functionality allows Omnis RESTful APIs (ORAs) to be fully defined using a “Swagger” definition, which is the most widely used standard for defining RESTful APIs.

Omnis RESTful 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.

See the tech note: TNWS0003 for information for implementing your own Web Services.