REST (Representational State Transfer) is a software architecture style consisting of guidelines and best practices for creating scalable web services. REST has gained widespread acceptance across the World Wide Web as a simpler alternative to SOAP and WSDL-based web services. RESTful systems typically, but not always, communicate over the Hypertext Transfer Protocol with the same HTTP verbs (GET, POST, PUT, DELETE, etc.) used by web browsers to retrieve web pages and send data to remote servers.
Added in version 10.96, ICONICS' WebAPI includes a REST interface that is secured using OAuth 2.0, allowing clients to not only read data, but also write to points and browse the address space.
This document will guide the user through the steps necessary for configuring and using the WebAPI's REST interface.
Follow the steps in the link below to set up IIS to use SSL.
https://docs.microsoft.com/en-us/iis/manage/configuring-security/configuring-ssl-in-iis-manager
At minimum, for testing purposes these settings should be configured, but you most likely want to take additional steps on a production server (such as obtaining a certificate signed by a valid certificate authority and disabling the HTTP binding).
Under your IIS server's main page, a self-signed certificate should be created.
HTTPS should be added to the Default Web Site's bindings, using the certificate created above.
Note: ICONICS highly recommends that self-signed certificates be used for testing or demonstration purposes only, not for servers in production. Self-signed certificates may not protect against certain types of attacks when used incorrectly.
Global Settings
Open Workbench.
Expand Security.
Edit Global Settings.
Go to the Web Login tab.
Make sure Enabled is checked under General Settings.
In the OIDC Provider / OAuth Authorization Server Settings section, set Signing credentials type to From the windows certificate store.
For Certificate Identifier, choose a certificate that will be used to sign the tokens provided by security.
Apply the changes.
OIDC Relying Parties
In Workbench, expand Security.
Create a new OIDC Relying Party.
Give this OIDC Relying Party a name according to the REST client you are configuring, for example, TestRESTClient.
Make sure Enabled is checked.
Configure the rest of the OIDC Relying Party entry as desired. This information must match the information used by your client REST application. If you only plan on using the Postman REST Client as your test client, as described in the "Example REST API Client: Postman" section, these settings are suggested:
Check Require client secret.
Enter a Client secret. Note the value for later.
Set Redirect URIs to http://localhost.
Check Allow refresh tokens (a.k.a. Offline Access).
Make sure you have at least one user created in the Users folder of Security. OAuth 2.0 does not allow anonymous connections. We need at least one user to authenticate with the REST API. The user requires security permission to read and write to the points that will be accessed via REST.
Note: If you are setting up a test or demonstration system you can edit security's Global Settings and change Security active to Testing. This mode makes for an easy testing environment by allowing full permissions when no one is logged in, but enforces permissions when a user is logged in. This allows a user to be present without requiring security to be enforced across the whole system. Testing mode is not secure and should never be used on a production environment.
Note: If you only plan on using the Postman REST Client as your test client, as described in the "Example REST API Client: Postman" section, these steps can be skipped.
In Workbench, go to Tools > Platform Services Configuration.
On the Basic tab, set Public origin to match the address configured in IIS. For example: https://servername.website.com
Select OK.
By default, the ICONICS Web API service is configured with a startup type of Manual and is not running. In order to use the WebAPI's REST interface this service must be running. You may also wish to change the startup type to Automatic or Automatic (Delayed) to ensure the REST interface continues working after a machine restart.
1. Open Services. This can be done in several ways:
Open the Start menu, search for services, then select the Services desktop app.
Or open Task Manager, go to the Services tab, and select Open Services at the bottom.
Right-click the ICONICS Web API Service and select Start.
Optionally, to change the startup type:
Double-click on the ICONICS Web API Service to open its Properties.
Set the Startup type to Automatic or Automatic (Delayed).
Select OK.
Once the above steps are followed the REST API is ready to be used. This section will use a free test application called the Postman REST Client to demonstrate how to access the REST API from your REST clients and ensure it is working properly.
Note: ICONICS does not create or maintain the Postman REST Client. We cannot troubleshoot or resolve issues with this client. The steps below may vary from the actual application as it receives regular updates. Please see the Postman website or documentation for issues or help with the Postman REST Client.
Install the Postman REST Client from https://www.postman.com/product/rest-client/.
Run the Postman REST Client.
At the bottom of the login page you may select Skip signing in and take me straight to the app.
If you are using a self-signed certificate, go into the Postman settings and turn off SSL certificate verification.
Create a new request.
Set the type to GET.
In the URL field, enter this address: https://hostname/fwxapi/rest/data
Go to the Params page or section.
Add one parameter, pointName, with a value of @sim64:Float.Random(1,-50.0,50.0,0).Value.
Go to the Authorization page or section.
Set the authorization type to OAuth 2.0.
Select Get New Access Token.
Use these values in the access token:
|
Grant Type |
Authorization Code |
|
Callback URL |
Same as the Redirect URI in the OIDC Relying Party. |
|
Auth URL |
https://hostname/fwxserverweb/security/connect/authorize |
|
Access Token URL |
https://hostname/fwxserverweb/security/connect/token |
|
ClientID |
Name of the OIDC Relying Party. |
|
Client Secret |
Same as configured in the OIDC Relying Party. |
|
Scope |
fwxserver offline_access |
|
Client Authentication |
Send as Basic Auth header |
Select Request Token.
Log in with the credentials of an ICONICS security user.
Select Grant access.
Select Use Token.
Select Send.
In the results section, you should see a JSON including the point name, value, timestamp, and quality.
See Also: