How to Get & Post RESTful API Requests

How to Get & Post RESTful API Requests


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

1 thought on “How to Get & Post RESTful API Requests”

Leave a Reply

Your email address will not be published. Required fields are marked *