Creating web services in Uniface efficiently

Web services are everywhere, although we are not usually aware of them. When you check the weather forecast on your mobile device, for instance, you are probably using one or more web services. The same is true when you make an online payment or use a Microsoft product on your computer. Most modern cars use web services too.

Users are unaware of these web services since they don?t have a user interface. Most people will never see a web service, and yet they use them on a daily basis.

So, web services are something that only software developers like you and me need to be concerned with. Fortunately, creating a web service in Uniface is very easy.

What is a webservice?

The most generic definition of a web service is a ?service offered by an electronic device to another electronic device, communicating with each other via the HTTP protocol?. SOAP is a well-known web service standard. SOAP has very strict definitions of content, and this content is always XML encoded.

What if you don’t want to use XML? What if you want to communicate something that doesn’t meet the SOAP content definitions? It’s important to realize that SOAP is a web service, but a web service is not always SOAP. An apple is fruit, but not all fruit is an apple. (Or, an Apple is a computer, but not all computers are Apples.

So, a web service is an application that is accessible via a standard web protocol, HTTP(S). Unlike web applications, web services are designed to communicate with other programs, rather than directly with users.

These two sentences imply a lot:

There are always (at least) two applications or systems involved.
Communication is done via the HTTP protocol.
- This means the receiving system must be able to receive HTTP requests…
- ? and the requesting system must be able to send HTTP requests.
- So, both must be connected to a network that is based upon HTTP. This must be the internet or an intranet.

The content of the communication is not meant for humans. So, it does not have to be in a readable layout format.

Connecting systems to something like the internet means that ports and firewalls must be opened. This turns building and deploying web services into something multidisciplinary.

And as with every communication, it is important (or even necessary) to use a protocol: to use the same grammar or speak the same language. This protocol can be XML, JSON, PDF or whatever you want, as long as both sides of the communication agree on using it.

Web services in Uniface

Building a web service in Uniface is possible. That much is obvious: you can build nearly everything with Uniface. But it?s more than that. Web services and Uniface are a perfect match. As I have shown in a?previous article,?moving services to the server is very easy. Execute a (stateless) service on a server and you?ve nearly got a web service. Taking that article as our reference, what do we need to change?

Creating a webservice

Communication between a Uniface client and the Uniface server is communication between two computers, so we?re already part of the way there. But to turn a Uniface service into a web service, communication must be done according to the HTTP protocol. That?s different from the TCP protocol and is another layer in the communication process. To use the HTTP protocol, as used on the internet, a?web server?is needed. Uniface is shipped with?Tomcat, which is perfect for this job.

Not DSP or USP but SVC

Hopefully, I am not telling you anything new so far. You have probably already built a web application or used web-based components in your application. That has been possible since Uniface 7, using the USP or DSP component type to create an HTML page that the user can view in a browser. That is not a web service, but a web page. A web service does not have a user interface. It is meant for communication between computers, systems or applications. In Uniface, the service component type SVC is ideal for this.

JSON or XML

A SOAP web service must always use XML. If you want to build a SOAP web service by the way, please?refer to the Uniface help. Uniface has native support for SOAP. But as mentioned above, there is more than just SOAP. In the definition for web services there are no specific requirements for the protocol used to describe the content of the communication ? as long as both parties agree to use the same one, of course. Between two Uniface processes or applications, Uniface’s?struct?format is perfect. However, other systems might not understand this so we are fortunate that Uniface offers the?structtojson?and?structtoxml?statements to convert a struct to JSON or XML.

Your first web service in Uniface

According to the definitions, even a simple string returned by a service on the internet is a web service. Let’s take that basic thought and implement it in Uniface. We?ll start with a service returning the text ?hello world?. Later, that will be enhanced to deliver JSON.

The architecture I described in?Move the data connection string to the server: why and how?will be used as the starting point. That architecture has the IDE on the client, and the output of the resource is automatically moved to the server.

All we need to add to the architecture described is to configure Tomcat on the server and create a service that can be called by the web; from that point, the service can be called a RESTful service.

Sketch of a deployment structure — Sketch of the deployment architecture I want to create. Not the best drawing, but this is the way I draw when I think about subjects like this.

CONFIGURING TOMCAT

Installing and configuring Tomcat is something developers probably don’t do on a daily basis. There are many books about this topic and covering it in just a paragraph in this article would be impossible. But again, we Uniface users are lucky since Uniface installs Tomcat automatically. All you need to do is configure it for your own project. If you run into problems with Tomcat, asking your system administrator might help. On your own computer or a VPS, the defaults from the Uniface installer will be sufficient.

There is a very close connection between Tomcat, the URouter and the UServer. The Uniface documentation offers a lot of information about this. Start?here, for instance.

A tip for configuring Tomcat is to put a test.txt file in the root of the webapp. In a browser you should see the content of the test.txt (link to demo) file without worrying about the URouter and UServer config.

As soon as Uniface?s URouter is included in the process, remember that the result in the browser is created by URouter. The color of the page that is returned is very important. If you receive a white screen, then the URouter is not activated at all, and it is Tomcat that is returning what you see. A red screen is created by URouter and it indicates that the UServer has not started. In most cases, this is because of something in the urouter.asn or user permissions on the server. A yellow screen makes me happy, because it means the UServer was able to start. The error code (that is $procerror as we know from Uniface) and the message on the page will help you solve the problem.

The Uniface service

With a config like this, you can develop on the client and test from a browser. Let’s now create our first web service.

A web service is a normal Uniface service, and so the regular Uniface rules apply. Let’s assume the service is called MY_FIRST_WEBSVC. Since every Uniface component must have at least one entity painted, just paint an entity on it (a ?not in database? will do for the test).

Now add an operation: ?Hello_World?. This operation will return the text string ?Hello World? to the browser.

In returning something to the requesting application the function?$webinfo(“output”)?must be used.

The first version of the operation will look like:

operation hello_world
$webinfo("output") = "Hello World!"
end

This is enough for a first test from a browser. Although I already know this is not good enough, I want to show you the result I receive in the browser.

A common mistake is to use a URL that does not specify the operation but only the service. Something like?http://uniface.unividuals.com:8080/restful_demo/wrd/MY_FIRST_WEBSVC.

Yellow page returned by the Uniface server

The browser shows a yellow page, telling me the result is created by the UServer process. This is good to know, but the page itself is not something I want to see. It tells me the service was found but the UServer process was unable to execute it. In fact, we did not test the ?hello_world? operation at all, but just the exec operation. If the operation desired is not specified, Uniface will start the exec operation as a default. (Personally, I don?t like to use the exec operation on the web. I prefer to specify one operation per task.)

To start the service in a particular operation, that operation must be included in the URL: specifically, it must be added to the end of the URL, using a period (.) or an asterisk (*) as the separator between the component name and the operation:?http://uniface.unividuals.com:8080/restful_demo/wrd/MY_FIRST_WEBSVC*hello_world

Yellow page in browser, difference between this one and the previous is the text " hello world"

The current script in the operation is not sufficient. From a security perspective, it is mandatory to specify per operation whether or not that operation can be activated in a web process. To be able to activate this operation via the browser, ?public web? must be added.

operation hello_world 
public web 
$webinfo("output") = "Hello World!" 
end

After compiling and refreshing the browser:

Congratulations! You?ve just built your first RESTful web service in Uniface.

This article is also published on Uniface’s website: https://uniface.com/updates/your-first-restful-web-service-in-uniface