Omnis Technical Note TNWS0002 December 2014

RESTful Web Services: implementing a Client

For Omnis Studio 6.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, there is a new JSON external component in Omnis Studio 6.1, called OJSON, 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 section in the ‘What’s New in Studio 6.1’ (Whatsnew61.pdf) for full details about creating web services using the new components.

Creating a Web Services Client

The External Objects group in Omnis Studio now includes a group called Web Worker Objects. Currently this contains HTTPClientWorker which is an HTTP Worker Object. This worker object functions 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, you need to define two methods, $completed and $cancelled, which the client worker calls with either the results of a request, or to say the request was cancelled. 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 (library compatible with Omnis Studio 8.x or above)
View the online example app

REST WEATHER

The example library presents basic weather forecast information by consuming a web service provided by WorldWeatherOnline.com. To use the web service consumed in the example library, you must obtain a trial API key from WorldWeatherOnline.com and enter the key when you open the library. To obtain your own API key you need to go to www.worldweatheronline.com and request a Premium Trial key which allows free testing for 60 days

To test the web service and display the weather forecast, open the example library, right click on the jsWeather remote form and select 'Test Form' from the context menu. The form should open in your desktop browser and show the 5-day weather forecast for Saxmundham. Since the example library uses the free version of the API and there is limit of 5 queries per second, the world data on the World tab is generated by batching the cities and using a timer to prevent a server error. If you publish the form to a webserver, when the form opens, it will try to identify your location using the IP address returned from the remote task.

When examining the code in the example library, the key methods are getWeather, getData, readCurrentData, readForecastData in jsWeather and $completed, $returnVal in the oRest object class. The following method is from the example library – 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.worldweatheronline.com"
; iHTTPMethod (Int) set to kOWEBhttpMethodGet
; iHeadersList (List)
; iContentChar (Char)
Do iHeadersList.$define(iHeaderName,iHeaderValue)
; 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 new OJSON external component can be used to process the JSON output: see the example library for techniques you can use with OJSON, and the 'What's New in Studio 6.1' PDF 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. The new functionality allows Omnis RESTful APIs (or 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.