Retrofitting the REST API – Setting up a reverse Proxy

The PLCnext REST Interface is a fantastic tool both to present and receive data from a back-end system. REST, or REpresentational State Transfer, is a software architecture style consisting of guidelines and best practices for creating scalable web services. There is a lot of great information already on the PLCnext infoportal, be sure to check it out! The URI’s provided by the PLCnext Firmware are perfect if you can build your system from the ground up. However they are not ideal if you want to retrofit an existing REST interface on the PLCnext. This blog will show you how to set up your own URI’s and connect them with your variables with a reverse proxy. We start with setting up a small example and work from there!

Prerequisites

I’m using an AXC F 2152 controller with FW2020.6 and PLCnext Engineer 2020.6. But the same should be possible with previous versions later then 2020.0. I’ll be using PuTTY to set up an SSH connection and postman to handle my HTTP requests. I have disabled the authentication for development purposes, you should not do the same in production! The instructions for PLCnext Engineer will be given very high leveled, not sure what to do? Take a look at the PLCnext infoportal and instruction video’s and/or compare with the sample project! The controller I’m using has the IP adress 192.168.10.10, please change this to the IP address you’re using.

Example

In this blog I’ll be using a simple pump UDT as an example. You can download the sample program from this GitHub page, or of course create your own. Turn of the  use of “user management” in the eHMI settings and create a global variable. Use this variable on an eHMI page so we can use it in the API.

The First API call

Maybe we should first discover what exactly we are changing in a few moments!
Let us send a GET request to get the value of our first pump.

Use Postman to send the a GET request to the following URI:

GET https://192.168.10.10/_pxc_api/api/variables?paths=Arp.Plc.Eclr/Pump1

(You can change Pump1 to your own variable)

The result is:

{
 "apiVersion": "1.4.0.0",
 "projectCRC": 3448945666,
 "userAuthenticationRequired": true,
 "variables": [
 {
 "path": "Arp.Plc.Eclr/Pump1",
 "value": {
 "xStatus": false,
 "iNumberOfStarts": 0,
 "sStatus": ""
 }
 }
 ]
}

Setting up a custom endpoint

Open up a shell session, create a root password an log in as the root user.
Next, type following command in your terminal, go to the “bottom” of the terminal and be careful not to type something in the meantime!

nano /etc/nginx/nginx.conf

Copy paste the next part into the terminal and save with ctrl + s and close with ctrl +x.

location /Pump1 {
 proxy_pass https://127.27.0.1:443/_pxc_api/api/variables?paths=Arp.Plc.Eclr/Pump1;
 }

Sending a request to the new endpoint

Send a new GET request with postman, this time to the next URI:

GET https://192.168.10.10/Pump1

Received the same answer? Congratulations your proxy was set up successful!

Setting up multiple pumps

Ok, but what if I’ve multiple pumps? Well, one approach could be do make an array that houses are pump UDT. You can get the whole array by calling the variable or just the element you’re interested in by specifying the index you want between right brackets, for example Pump2[1] will give you the element with index 1 in the array named Pump2.

But that’s the subject of this blog. We can also set up the proxy in a way that we can get access to multiple pumps.
Modify the text pasted in the previous steps to match the next scheme:

location /pumps {
 proxy_pass https://127.27.0.1:443/_pxc_api/api/variables?paths=Arp.Plc.Eclr;
 }

Sending a GET request with postman to the first URI will give you the same as before. Sending a GET request to the second URI will give you an array of the same datatype.

https://192.168.10.10/pumps/Pump1

https://192.168.10.10/pumps/Pump2

Now you should have everything to match whatever API scheme you encounter and integrated it in your PLCnext device!

Further readings

https://www.howtogeek.com/343877/what-is-an-api/

https://www.w3schools.com/tags/ref_httpmethods.asp

https://medium.com/@TebbaVonMathenstien/what-is-an-api-and-why-should-i-use-one-863c3365726b

https://restfulapi.net/rest-api-design-tutorial-with-example/