Category: Knowledge Base

If there are errors executing a REST API call, you can check the OAS Configuration app, click on the triangle icon (should be flashing of there's an error) and you'll see system errors.

Locate the REST API and expand it out and you should see the failed calls. But it often won't give you the detailed HTTP request/response and just contain the failed URL that was attempted. It's a good way to see if people are hitting incorrect endpoints.

If you use Postman to execute REST API calls, you can see the proper URLs, headers, body contents, etc. for making proper calls.

If you ever get these response or codes, this is what they mean:
401: Unauthorized - you have not included the clientid and token fields in the request header, or the session has expired
500: Unknown server error - this may be something we need to investigate since the data was submitted properly but an error occurred on the server processing the request.
404: The object you're trying to GET or PUT (update) does not exist

If you see "Service Unavailable" that means the REST API did not start up properly.
If you see a message indicating the Endpoint does not exist, this means the URL is not correct for the call.

If there's something specific you're attempting and don't know what the issue is, you can always look at a successful call from Postman's console and it will expose everything in the request header/body and response header/body. You can compare it to your failing call to see what you might need, such as the correct Content-type. You can always let us know what call you're stuck on and we can investigate why it might not work for you.

REST API

The OAS Platform REST API, like all APIs is a programmatic interface. It allows developers to read and write real time Tag data, read real time and historical Alarms and Trends, and even create or update Tag configurations. Because it utilizes JSON data over HTTP(s), it can be used by any virtually any development platform or language. It is also a perfect alternative to the .NET Data Connector for applications not running .NET code. Developers need to handle client to server communication to the API within their code. This includes web technologies such as Javascript, but if browser visualization is required, Web HMI may be the preferred product to utilize.

REST API Language Support

• Any language that can support sending JSON over HTTP/S (.NET, PHP, Python, JS, NodeJS, Java, and more)
• Fully documented and interactive API found here

Typical Applications

• Automated solutions without the need for a user interface or data visualization
• Programmatic configuration of the OAS Platform when using the .NET Data Connector is not possible (e.g. your platform is not .NET)
• Native mobile applications

Skills Required

• Knowledge of HTTP processes and methods
• Familiarity with JSON object structures

Learn more about the OAS REST API >>

Web HMI

The Web HMI product is specifically geared towards web applications that need to visualize real time and historical data. It consists of a set of Javascript libraries intended to be included in your web pages which handle server communication and screen updates. While the Web HMI product does include programmatic methods for reading and writing Tag data, development is strictly done within HTML and intended to be run in a browser.

Web HMI Language and Platform Support

• Any web application platform - built on standards (HTML, CSS, Javascript)
• Any web development platform
• Purely a Javascript solution for browser-to-OAS communications

Typical Applications

• Real time and historical data visualization
• System management and control user interfaces
• Browser-based desktop and mobile applications

Skills Required

• Web application development skills
• Familiarity with JSON object structures
• Javascript skills for direct access to the Web HMI script library functions

Learn more about OAS Web HMI >>

REST APIs by their very nature are HTTP services. This means that they are based on a request/response model. They are not event-driven and not capable of pushing data to a destination. You can poll against the REST API for updated values, but the data is only as current as the polling rate. So if the polling rate is longer than the refresh rate on the server value, you may miss updates. If you would like to move data based on events, you must write your own solutions using one of our other developer tools, such as the .NET Data Connector or the Universal Driver Interface.

YES! There are two levels of security when using the REST API. The first is the authentication required for all operations. You first perform an authentication call using a credential configured within the OAS Server. Then, you can encrypt all communications over the wire by using an SSL certificate and restrict the REST API to using only SSL communications.

The security token and client id granted to the caller after authentication represent a REST API session. As long as the server remains active (not rebooted), and the credentials are continually used, the session will not expire. If there is no activity on the session after 30 minutes, the session will expire and a 401 Unauthorized response will be returned for all operations. This idle timeout can be configured on the server using the OAS Configuration app. Go to Configure > Options, select your OAS server (usually localhost when configuring the current machine) and then go to the Networking tab. Here you can set the REST API Session Timeout in minutes.

The OAS Platform allows for connectivity and integration with many systems and devices. It also exposes tools for direct data integration and automation using .NET for Windows developers, and libraries for integration with web technologies. If you are developing custom software that runs on other platforms that do not host the .NET Framework, and if you prefer to develop more robust applications with or without user interfaces, the REST API is a perfect solution. It exposes functions for reading and writing real time and historical data, as well as operations for customizing the OAS tag configurations themselves.

The OAS REST API was developed as a standard REST API, and we have exposed our demo server for you to experiment with it using your own tools. We have also published the full REST API documentation online and have integrated it with the popular Postman tool. This free tool allows you to test operations without writing code, and then generate sample code to get you started. In fact, in our online documentation, just click "Run in Postman" and it will download the full API with examples to your Postman instance. Within Postman, you can then point to your own OAS server to test the REST API with your own data. Read more about Getting Started with REST API.

REST APIs expose data or operations in a system via HTTP calls. The OAS REST API is no different in this regard, so it is intended to be used by 3rd party clients and developer tools. If you would like to connect to another 3rd party REST API and integrate the data into OAS Tags, you can use either the .NET Data Connector, or the Universal Driver Interface to develop a custom solution.

Yes, the REST API as well as Web HMI can be run over SSL. You must first install an SSL Certificate on your server for the domain name(s) that you intend to use, for example “https://hmi.myserver.com:58725”. Once the certificate is installed properly on the server, check Use SSL and select the installed certificate from the dropdown menu. For detailed instructions, please see read:  Configuring OAS Web Services.  Purchasing and installing an SSL certificate is outside of the scope of the OAS product. For more information on Windows and Certificates, see the following article.