Omnis Technical Note TNWS0006 August 2020
Creating Omnis REST API endpoints and deploying them through IIS
For Omnis Studio 10.x or above
by Andrei Augustin, Omnis Engineering
Introduction
REST APIs are the current preferred standard for web services. With Omnis, you can both consume and serve REST web services. This tech note covers creating and serving an Omnis REST web service through IIS; if you are interested in finding out how you can consume a REST web service from within your Omnis application, please consult our other tech notes (TNWS0002).
First step, creating the REST web service
First, create a new remote task in your Omnis library and set the remote task's $restful property to kTrue. Next, set the remote task's $restfulapiname property to the name of your REST API, for this example my library name will be restfulServer and the remote task's $restfulapiname restservice. Now create a new URI endpoint for the REST remote task. To do this, go to the remote task's methods, right-click and select Insert New URI. I will call mine /helloworld:
Next, right-click on the new URI (/helloworld in this example) and select Insert New HTTP Method and from the menu choose $get, for example:
Now we have a $get API endpoint that will run on [server IP address]:[server port]/api/[library name]/[URI], which in my case would be http://192.168.0.14:9800/api/restfulserver/restservice/helloworld. By the way, you can set the server port in the $serverport property of Omnis (click on Omni Studio xxxxxx in the Studio Browser and select Prefs). You will have to close and reopen your library if you change the $serverport property.
The API doesn't do much right now though! It doesn't even return an outcome code to the client, in fact if we were to use Postman to send a GET HTTP request to to our API:
we'd get back a 500 error:
This is not good, so we need to make our API endpoint do something. Let's tell it to return a message to the client and a status code of 200 (meaning success).
In our remote task's /helloworld $get method, let's make a call to $sethttpstatus and send a Quit method with “hey there”:
And let's not forget to set our return type to text/plain:
If we make the API call now from our Postman client, we will get a 200 returned as well as the “hey there” message!
Second step, running IIS with Omnis RESTful
Now that we have an API endpoint working in Omnis, it's time to put a proper web server in front of it, so let's use IIS.
We can follow the tech note TNJS0003 which explains how you can deploy the Omnis App Server, but with some minor changes: alongside the omnisapi.dll, we will deploy the omnisrestisapi.dll too in order to serve the API endpoints to clients. The process is exactly the same as described in TNJS0003 for omnisapi.dll, but using omnisrestisapidll instead:
Now, since we are going through the web server, our API endpoint needs to change a little bit, since we need to go through the omnisrestisapi.dll, so it becomes:
http://192.168.0.14/cgi-bin/omnisrestisapi.dll/ws/9800/api/restfulserver/restservice/helloworld
And as you can see from the GET request from Postman, we successfully received our message back from the Omnis Server whilst the API request went through the IIS server!
Using a Swagger file
As you may already know, Omnis is compatible with Swagger and therefore it creates a Swagger definition of the API endpoint. If you wish to retrieve the Swagger definition, using our example above, you could make an HTTP GET request to:
http://192.168.0.14/cgi-bin/omnisrestisapi.dll/ws/9800/swagger/restfulserver/restservice
Obviously, if you do not wish to go through the IIS web server, you can just ask the Omnis Web Server directly by querying:
http://192.168.0.14:9800/swagger/restfulserver/restservice
You can get the swagger API endpoint by going to Web Service Server > library name > RESTful API name, and select the Swagger Definition option:
If you use a web server, here's where the $restfulurl Omnis property comes into play. If you have your own domain name, you can set it in the $restfulurl property and the swagger definition will change accordingly:
This is especially important if you actually plan to use the Swagger definition to consume an Omnis-based RESTful API endpoint from another system.