Omnis Technical Note TNWS0002 Updated Oct 2019

REST Web Services: implementing a Client

For Omnis Studio 10.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 REST 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 REST 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 REST 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 REST 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, 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 REST web service. 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: bit.ly/OmnisWeatherApp (accesses the same app, but this shortcut is easy to type on your phone)

REST WEATHER

Downloading the Library

Download the library here: RESTWEATHER.ZIP (library compatible with Omnis Studio 10.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 10.1.x which you can download here: www.omnis.net/download

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

Examining the RestWeather Library

The example library presents basic weather forecast information by consuming a web service provided by openweathermap.org. To use the web service consumed in the example library, you must obtain a trial API key from openweathermap 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; you can click on the 320 and 768 breakpoints to examine the layout for each.

The form defaults to the location Saxmundham (the Omnis development center). 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 and $completed in jsrWeather. 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.openweathermap.org/data/2.5/weather"
# The full URI sent has the API key, location appended as well as an optional parameter to return the data in metric format
# 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 jsrWeather form in the example library:

# called by the client worker with the results
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 REST APIs (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.

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

 

Search Omnis Developer Resources

 

Hit enter to search

X