00:03
RESTful web services provide a lightweight and secure way to move data
00:07
between devices using hypertext transfer protocols. REST or representational state
00:13
transfer is supported by both the SNAP PAC and groov api's to make data
00:17
store, variable and i/o tags available over either HTTP or HTTPS. In this
00:24
workshop I'll go over how to make both groov and SNAP RESTful requests,
00:29
view the results, make API requests from Python and the command line, and finally
00:33
I'll use the software app named Postman to interact with the API.
00:43
I will be posting data to and getting data from both this groov box and this
00:47
SNAP PAC Learning Center. The groov box is an industrially hardened edge
00:51
computing appliance preloaded with software for creating and serving mobile
00:56
and web-based graphical user interfaces. The groov box also includes Node-RED an
01:00
IOT application development environment. The Learning Center is basically a SNAP
01:05
PAC system with a controller, several i/o modules, and a rack we use for training here
01:10
at Opto 22. This front panel simulates some typical i/o signals like a meter,
01:15
temperature sensor, potentiometer, LEDs, switches, and a buzzer. The controller is
01:22
running a convenience-store strategy that's loaded into its memory. Since I
01:26
already have a list set up I'll go into the browser and get started building the
01:29
request URL from the groov box. I'll bring open the REST API interface
01:35
by going to my groov box's help and selecting groov public API. Even if you
01:43
don't have access to a groov box this reference page will be available in a
01:46
link below. Here you can also find the Opto 22 developer site with links to the
01:51
groov REST API and a whole bunch of other things. Here I'll bring this open
01:57
and I can see how to build my URL.
02:05
The most basic goal is pretty straightforward all I need is HTTP colon
02:10
slash slash my host name slash API slash v1 slash data store and then whatever
02:15
I'm getting. In this case just a list of tags and I followed that with my API key.
02:19
I'll enter this URL into my browser and make sure to authenticate it using an
02:24
API key and the field question mark API
02:27
underscore key equals and then supply my API key. When I hit enter I can see the
02:35
full list of tags from all the devices and all the data stores on my groov box
02:40
right now I'm viewing the JSON object through a browser extension so that the
02:45
sections are collapsible and the text is colored. But this isn't the only
02:50
information that's available to me using this reference page I can see that I'm
02:55
able to request information about the groov instance that I'm running, the
02:58
users whose API key I'm using, as well as reading and writing specific tags. In
03:03
order to do that I'll need a specific tags ID number so I can pick one from
03:07
this list I just got like tag number 84 sunrise.
03:14
All I have to do to read this tag is put in the URL slash read slash the ID
03:20
number and there we go. I can see that the Sun rises at 6:32
03:32
a.m. now. The SNAP PAC controller on the developer site there's another link for
03:40
the SNAP PAC API on this page. There's a link to another REST API reference page
03:48
that you can use to help build your URLs.
03:52
Here you can see the exact URL extensions you'll need to access
03:56
everything on the PAC from analog and digital i/o to strategy variables and
04:01
even details on the device and firmware. Using this reference page you can easily
04:06
set up the exact URL you'll need for your application. You can set up your
04:10
SNAP PAC controller for either HTTP or HTTPS. Mine is set up for HTTP here in my
04:19
browser. I'll build a URL to go to my controller's IP and then this part of
04:26
the API URL is very similar to the groov's API. I use API /v 1 slash device
04:33
slash strategy to get into my device then I have to specify whether I'm
04:39
reading an i/o point, a variable, or a table. Here I'm getting the i/o from the
04:44
analog inputs called fuel level. Reading analog inputs and outputs I also have to
04:50
specify that I'm getting the engineering units of this point. When I hit enter
04:54
I'll be asked for basic authentication credentials which I already configured.
04:58
When I enable the restful interface you can manage these at your controllers IP
05:03
slash admin slash keys. Once I enter my ID and value into the request pop-up and
05:08
log in I'll see a JSON object holding the potentiometer's current value. If I
05:15
were to change the fuel level and then make this request again I get a
05:20
different value so we know it's live.
05:26
Now that I've created and tested some SNAP and groov URLs in the browser
05:30
I'll take them over to a Python script and show you how you can
05:33
programmatically make RESTful requests both get and post for both the SNAP PAC
05:37
and groov APIs using the requests library. First you'll want to make sure
05:44
you import requests if the library isn't showing up you'll need to use PIP to
05:48
install it. From here I'll read the i/o's digital output points without a specific
05:55
variable in mind and I don't need engineering units since I'm reading
05:58
digital not analog points. I handed my host IP address, build a URL, and hand
06:05
that to the requests library. It's important that when making the get
06:11
request that you include the field both equals and hand in the ID comma value
06:15
key set to the requests function as a parameter otherwise you won't be
06:19
authorized. Once I've made the request I can get the results back using G content
06:26
to get the content and then dot the code to turn the bytes into a string. When I
06:32
run this script I'll see that the list includes an alarm that is currently
06:36
turned off a freezer door that is closed and inside and outside lights that are
06:40
both turned on. To give you an example of a post request I'll turn the inside
06:45
light off. So I'll start by setting my variable string to hold inside light.
06:53
Since I'm changing the state of this variable I will need to append slash
06:58
State at the very end. Since I'll be making a post request I need to change
07:03
my function from get to post and will also need to hand in some data. That data
07:11
will be a JSON object so I frame it with curly braces. What I'm putting in is the
07:18
value and I'll be handing it the boolean value false. To make sure that this is a
07:23
boolean value and not a string I make sure not to put quotes around false but
07:27
since the value is a string I'll need to use the backslash quote escape character
07:31
to insert the quotes in the middle of the string.
07:37
Once I'm handing this data and my authorization credentials in I can save
07:42
my script, execute it, and see the inside light turn off. All it would take to read
07:52
and/or write from any other i/o point or variable in the PAC controller is a
07:56
couple of minor changes in the URL I just built with the same requests
08:03
library. I can use Python to access my data store tags in my groov box. Since
08:08
they're such different devices I'll start a fresh request and comment out
08:11
the SNAP PAC code. I'll scroll down and un-comments some code I prepared earlier.
08:21
This is going to check my groov box for the tag number 127. It holds a list of
08:27
earthquakes in my groov box. I'm going to be reading this tag so I set that as the
08:32
command and hand in an extra parameter with count equal to five. To make sure I
08:36
get all five values from the table here I could also set an index parameter to
08:42
set where I start the count. The other parameter I'm handing in is my API key.
08:46
Note that the SNAP PAC used basic authentication to get in but the groov
08:51
box is using query parameters so I don't need to hand in my authentication to the
08:55
function I just need to append it at the end of the URL using question mark API
09:00
key equal to my API key string.These query parameters attach to the URL need
09:05
to be separated by commas which is why that character is there but it also
09:09
means that I don't need to hand them in to the request function. I just need to
09:12
set verify equal to false since the groov box only allows requests to be
09:16
made over HTTP. I'll save this script and run it and I can see all my earthquakes
09:25
appear in the window below.
09:31
Now I'm going to overwrite one value in the table and I can only do one at a
09:36
time using the API. If I wanted to write to a single tag rather than an item in a
09:42
table it would be exactly like this only I wouldn't set the index tag. Since I am
09:47
writing to a table I'll set my index equal to three so I write to the third
09:52
item in the table.
09:57
Since I'm using the groov API I won't be handing in the value to the request
10:02
function it is also a query parameter so I attach it with the '&' value
10:06
equal to and I'm gonna hand in the string hello from Python. Note that I
10:16
used the plus symbol between words in the value string since this is a URL and
10:20
the space character would not be valid. Here I can rebuild the URL the same way
10:24
and all I need to do is change my request start get function to request
10:28
stop post, keep my URL and verification on false, and I'm good to go. Now I can
10:37
save the script and execute. It and went through successfully so now we'll go
10:43
over to groov, bring open groov view, and I can see that the 4th earthquake in
10:52
index 3 since it is zero-based is now holding the string hello from Python. So there we
10:59
go that's reading and writing SNAP PAC
11:01
controller tags and groov data store tags using their quests library to make
11:05
RESTful api calls programmatically.
11:13
So now I'll take these requests to the command line.
11:18
I'll bring open this prompt and the command I use is curl. First I'm going to
11:25
hit the groove API so I have to disable SSL Certificates with - k then I can use
11:32
the same URL as I did in Python. I make this request and there is the list of
11:39
five earthquakes and to make a post I can use curl - K - capital X followed by
11:48
the keyword post to set my request type. From there I can use the same URL as I
11:55
did in Python and I'll just make a few changes. I'll go through and change the
12:00
read command to write, select index 4 to get the last item in the table and hand
12:09
in the value hello from command. Now I'll make this command,
12:21
go back to groov view, and I can see my change string up here. Here
12:31
the SNAP PAC request is done similarly but rather than using - K to allow an
12:38
unknown certificate like with the groov box you use - - user and your key value
12:43
pair to authenticate, then the URL will be the same as Python and the browser.
12:54
Make sure that the entire URL is exact because a single typo will cause the
12:58
request to fail. Then when posting to a PAC controller use - ex post to set the
13:07
request type - - user for basic authentication and then - D followed by
13:14
the JSON value string. Set the data that you want posted. I'll use this
13:23
instruction to turn the inside light back on from the command line. It's that
13:30
easy to use SNAP PAC and groov api's with curl. Anywhere that you have curl
13:35
access you can get your Opto data.
13:42
Finally another way you may want to use these api's is from Postman. Postman is a
13:48
powerful developer app designed to test develop and document api's and makes
13:52
building simple and complex HTTP requests fast and straightforward. Now
13:57
that you've had some exposure to the api's Postman will be really easy. Recall
14:02
that the PAC uses basic authentication. So, hand in your ID value pair then all
14:09
you have to do is put in the request URL and hit Send. Here I'm showing the list
14:17
of all the int 32s on my device. You can see that fuel low limit is set to 1000.
14:24
I'd like to increase that to 1500 to do that I'll switch from get to post and
14:31
hand in a body parameter the holds the raw text JSON value 1500.
14:44
I also need to specify that I am changing the fuel low limit. Now I can
14:52
hit Send, make the get request again, and I'll see that the value has changed.
15:07
To access the groov API I have SSL Certificates disabled so I
15:12
can enter the URL right away.
15:23
Instead of handing in basic authentication I'll disable that and
15:28
hand in my parameters using this feature of postman. Here I can set my query
15:37
parameters like count of five and my API key and you can see that they're
15:49
appended directly to the URL. Now when I click send on my get request you can see
15:56
the table up here below including the hello from Python and Hello command
16:00
changes I made earlier.
16:12
To make a post I'll set the index parameter - to disable the count
16:18
parameter and also hand in a value holding hello from Postman.
16:32
Now all I have to do is change the request type from get to post and change
16:40
the URL from read to write. Now when I hit Send I get confirmation, and if I go
16:50
over to groov I can see it updated in the list here as well.
16:55
Now with those URLs in and working it's possible to make use of all the
16:59
features of Postman including scripts, collections, and monitors. You can find
17:04
out more at get.postman.com. So it's that easy to use this SNAP PAC and
17:10
groov REST api's with everything from Postman to Python and even the browser
17:14
or command line. To learn more about these systems check out workshops.opto22.com
17:19
and developer.opto22.com. For more examples and assistance check out our
17:25
user forums at forums.opto22.com thanks for watching.