REST
REST is a client-server web service for requesting and transferring information through HTTP. The Server runs in MIX. This is set up in MIStudio in the logic by adding a REST Server. A REST Client can also be used which will get information from a REST Server.
The URL passed to the REST Server from the client (i.e., a web browser) will have the data request in it. Then the Server returns the data, probably as JSON but could be in any format. So this “API”, or how to request data and how this data is returned, is set up REST-server by REST-server (there is no per-defined format).
A good tutorial on the API and what REST is: https://www.restapitutorial.com/
Here's a very quick overview: http://www.restapitutorial.com/lessons/httpmethods.html
The same thing with a little more detail: http://www.restapitutorial.com/lessons/restquicktips.html
A lot more detail: https://www.ibm.com/developerworks/webservices/library/ws-restful/
Using in MIStudio
MIStudio REST Services
MIStudio supports both a REST Client and a REST Server
VIB now has two REST components: RESTServiceManager and RESTClient
The RESTServiceManager provides the server side of the REST interface. That is, you make REST calls to the RESTServiceManager and it provides responses.
The RESTClient provide the client side. It makes calls to a REST server and gets the responses.
RESTServiceManager
The basic properties of the REST Service Manager are All Applications (defaults to false), the HTTP Port, which is mandatory and a username and password, which is not. The HTTP Port defaults to 7220 but can be any valid HTTP port. The port appears in the requesting URL as shown in the examples below, which all use the default 7220 port. Also the basic property Publish Values which defaults to true.
If the “All Applications” property is set to “true” then values from the entire project will be available to the RESTService. The default “false” allows access only to servers in the current application only.
If “Publish Values” is “true” (the default) values will be published as described below. Set to false no values will be publish.
The Expert properties provide support for SSL.
A valid keystore, built with Java's KeyTool (or similar) is required to enable SSL. The path (full or relative) to the keystore is required. There are a number of resources describing how to do this, for example:
https://www.sslshopper.com/article-how-to-create-a-self-signed-certificate-using-java-keytool.html
https://docs.oracle.com/cd/E19798-01/821-1841/gjrgy/index.html
Using the RESTServiceManager
The RESTServiceManager responds to three verbs:
LIST VALUES and UPDATE
The services work with JSON object. JSON is a standard format for representing objects. More information can be found here:
https://en.wikipedia.org/wiki/JSON
LIST and VALUES are “GET” requests. UPDATE is a POST request.
Since web browsers use the “GET” method by default, just entering a URL in the browser will give you a response. So, for example, this:
will give you a list of all the available servers (currently also includes graphics which is a problem).
The LIST is returned as a JSON object, for example: <pre>
{ “Variables”: [ 11] 0: “/Main/annunciator” 1: “/Main/annunciator0” 2: “/Main/broadcastserver2” 3: “/Main/pushbutton” 4: “/Main/restclient” 5: “/Main/restservicemanager” 6: “/Main/swingtextfield” 7: “/Main/untitled0” 8: “/untitled/button” 9: “/untitled/randomdata” 10: “/untitled/setvalue” - } </pre>
VALUES will provide the value for any server in the LIST.
Since “broadcastserver2” is in the same container as the restservicemanager it can be requested with a simple path:
http://localhost:7220/VALUES/broadcastserver2
Multiple server values can be request in one call:
http://localhost:7220/VALUES/broadcastserver2/broadcastserver3/broadcastserver4
Since the '/' character is reserved in a URL in order to provide a full path, the characters “%2F” must replace the '/' in the URL. For example, to request the value of the “randomdata” server, the call might be:
http://localhost:7220/LIST/%2Funtitled%2Frandomdata
or, adding to the previous call:
http://localhost:7220/VALUES/broadcastserver2/broadcastserver3/broadcastserver4/%2Funtitled%2Frandomdata The response is a JSON Map with the servernames and values. For example:
{ “/main/BROADCASTSERVER2”: “0” “restclient”: “{ “id”: 4, “title”: “clever”, “author”: “no one”}” “Errors”: “NONE” }
The “Errors” tag will describe any problems that occurred with the request, however the return will be 200 (OK) as long as it was received and processed.
It should be clear by this point that the LIST is just providing server names from the MIStudio (or MIX) installation. The names are the names given to the various components in the application and the VALUES returned are the current values of those servers.
UPDATE allows those values to be set. UPDATE uses the POST method and so cannot be sent from the browser bar. A tool, such as the “Advanced REST Client”
is required. These tools are available for all major browsers.
UPDATE is expecting a JSON Map in the body of the message. So, for example, using this URL
with the following map in the body of the message will set the values for the five broadcast servers.
{“broadcastServer0”:“FIRST”,“broadcastServer1”:“17”,“broadcastServer2”:“14.5”,“broadcastServer3”:“Teest”,“broadcastServer4”:“last”}
Testing of the MIX RESTServiceClient can be done using Postman (as an alternative of using MIStudio with the RESTClient). For example, install (unzip) Postman and run it. To POST (set a value) to a manipulator in MIX called “broadcastserver”, select POST and enter this value in the URL:
http://192.168.5.145:7220/UPDATE
and enter this in the message body:
{
"broadcastserver": "23.80"
}
then press Send and you will see that the update was sent to MIX.
RESTServer Security
If a user name and password are provide at the rest server, the incoming request must include those as arguments in the URL. For example if the username and password are both set to “test”, then this URL would be required to UPDATE the server.
RESTClient
The RESTClient will send values from MIStudio or the MIX server to a REST Server. The basic properties of the REST client allow for the setting of the URL and the method.
If the RESTClient property “Publish” is true, and data is requested from the MIX server, or is returned with a name and value in the same format that MIX returns the data, then the data returned in the GET request will be published to a broadcast server with the same name as the data item. For example, MIX is running a RESTServiceManger and the MIX project has a server called “floatfluxserver” running. The RESTClient sends this GET command with this URL: http://localhost:7220/VALUES/floatfluxserver. The returned value will be a JSON string such as:
{
"floatfluxserver": "55.23"
"Errors": "NONE"
}
A BCS with the name “floatfluxserver” will update with the value “55.23” and a BCS with the name “Errors” will update with the value “NONE”.
The URL can also be set dynamically by exposing that property.
The bean has two default inports “trigger” and “input”. The trigger will send the URL with no body content. The input will use the string value of the incoming value as the body of the message. The body of the message will be sent with the request except for “GET” request.
With a simple “GET” request, the request is sent to the server and the body of the return is the output of the server. If the response is a JSON map and the “Publish Values” property is true, the values in the map will be sent to the named servers, as with the UPDATE of the RESTServiceManager. Otherwise the application is free to parse the data as appropriate.
With any request that is not a “GET”, if the “input” inport is used, the body will be sent with the request and the body of the response set out the output of the server. Values can again be distributed with the “Publish Values” property set to true.
Some expert properties further refine the operation of the client.
The content type of “text/plain; charset=ISO-8859-1” is probably a good choice for a “GET” or a “POST” with either no body or a plain text body. If the body of the request is a JSON map, then the content type “application/json” is probably a more appropriate choice. A huge number of content types are available. A, probably incomplete, list is, for example, here:
http://www.freeformatter.com/mime-types-list.html
The correct content type should be available from the provider of the server.
Secure (HTTS) urls can be used, but may require some configuration. If the target site uses a certificate is from a well know “Certificate Authority” (CA) no configuration should be required.
If the site uses a “self-signed” certificate, then the certificate should be imported into the Java runtime. Some description of how to do that is provided here:
https://docs.oracle.com/javase/tutorial/security/toolsign/rstep2.html
Alternatively, the “Validate SSL Certs” option can be set to false. In this case, the communication between the server and client is still secure, but the identity of the server has not been validated, opening up the possibility of a “man-in-the-middle” attack.
Testing the RESTClient requires a rest server. A simple JavaScript based server is available here:
https://github.com/typicode/json-server
This is very easy to install and use. Adding the section:
"values": {
"broadcastServer0": "FIRST",
"broadcastServer1": "17",
"broadcastServer2": "14.5",
"broadcastServer3": "Teest",
"broadcastServer4": "last"
}
to the db.json file provides a way to return the values for particular servers using the URL:
RESTClient Security
The RESTClient supports HTTP “Basic” Authentication. If the user name and password are set these will be sent as the “Authorization” HTTP header.
Testing
There are a few open test sites. For example https://jsonplaceholder.typicode.com/.
If you set the URL in the RestClient to http://jsonplaceholder.typicode.com/todos/1 and trigger the bean, you will get some JSON back, such as { “userId”: 1, “id”: 1, “title”: “delectus aut autem”, “completed”: false}