Use Swagger to make API calls with Node-RED

in this video i'm going to take http requests generated with swagger ui pages and show how to bring them into a node red flow this is going to cover the api endpoints the authentication methods and payload formatting swagger is just open source software that provides an interface for thousands of apis it's capable of documenting building and testing api calls from just one place i'll start by demonstrating a weather api that makes use of swagger then i'll move on to the groov manage api and show you how to dynamically toggle a vpn connection from node-red let's start with that weatherbit api as you can see this is used all over the world and they have a lot of documentation at the top of their home page that you can see here under resources if i bring open that weather api documentation you can see all the different endpoints they support and each of them have these swagger ui pages if i select that you can see right here that i have eight different requests i can make to get data for the current weather conditions i'm going to be doing it using the latitude and longitude today here you can see swagger gives us some notes on how this endpoint works and an example value of what the response is going to be formatted like before i even have to run it then i can put in my parameters right here in my browser for the latitude i'm going to use 33.4936 and for the longitude i'll do negative 117.1484 that's the location of opto headquarters here in temecula i can also change the units to be imperial but i'll leave the rest of these as default the last thing i need to do is paste in my api key now i am going to be deleting this key by the time this video was uploaded but if you want to try this out for yourself you can create your own account and generate your own api key once you've filled in all the parameter fields there's a try it out button right here that i can click and it's going to run this request right here in my browser and give me the response in real time it also generates the curl request that i would need to run this through a command line and the entire request url you can see in this case the api key does go right here in the url and that's how i actually authenticate this request so that it knows that i'm allowed to actually hit this end point i also get this rich body of data back that does in fact correlate to the weather in temecula i have just all sorts of information endpoints here including the current temperature it's 73.2 degrees fahrenheit and also i get the response code of 200 meaning this was a successful request now i can just take this request url select the whole thing copy it and paste it right here in my browser and you'll see i have a pretty print uh chrome extension here that shows me this nice laid out uh json object right here in my browser and i'm able to read the data just using chrome or firefox or any other modern browser but i want to be able to do things with this data and for that i'm going to be using node-red so let's bring this first url over into node-red and put it into an http request node here you can see i already have a node-red instance running i am going to shrink the node palette on here over to the left so that i have a little bit more space here the main thing is of course the http request node so i'll just control and left-click on the screen type in http and drop in a request node here i just need to make sure my method is set to get and i'll paste in that api url right here i know that it is in fact a get endpoint because if i come back to the swagger page right here we can see if i scroll up right here it says in the swagger that it is a get endpoint so now that i have my get set my url right here you'll also note that it is https and that means that this is a secure and encrypted endpoint so i will need to enable ssl tls configuration you don't have one by default but it's simple as clicking the pencil icon to create one we can just leave this empty since our authentication happens with that api key so there's no need to verify the server certificate or put in a certificate whether a self-signed certificate or a ca certificate if you're hitting a secure server that doesn't have a public certificate authority you may need to provide these files but in this case i can just go ahead and click add put this blank tls configuration in so that i'm able to have this enabled and click done now i just need to trigger this request and get the response back so to do that i'll just be using an inject node and because we don't need any payload to do this simple get request i'm going to go ahead and drop all of these properties off and just make sure i'm injecting nothing the main thing is that i'm setting off this http request node finally i want to see the response so i'll drop in a debug node double-click this and make sure that i'm viewing the complete message object so i get the entire response right here finally i do want to see that json so another thing i can do in the http request node is instead of getting a utf-8 string i will get a parse json object depending on what you're reading you may just want a string or a binary buffer but in this case we know that it's going to come back in json so let's just format it accordingly so we'll inject do our http request and then view that over here in our debug pane when i deploy and inject it'll make the request we'll get our weather payload back and we can see right here is our payload with our data which is an object of just one entry it's an array of one entry and when we open that up there we go we can see all of our weather data including the temperature here at the bottom and our city name here at the top so it's really straightforward to just get something like a simple get request find the url generate it right here in swagger and bring that over to node red so now let's take this example to the next level and we're actually going to do a post request and we're going to what we're going to do with that is we're going to toggle this open vpn connection on my groov epic right here and again we'll be using swagger to figure out what the endpoint looks like how to authenticate and we'll also need to send a payload body to control this so we can do that using the info and help tab built right in here in groov manage i'll just select that and click rest apis you can see that we have multiple apis available for pac control groove authentication groov view and of course groov manage now we do have node-red packages that do a lot of this functionality in built-in packages that you can download for node-red but not everything is included in those packages you can do things like reading and writing io but you can't do things like toggling the open vpn tunnel or unmounting your usb drives to do that though you can use the rest apis so if you select the link here under info and help it'll bring you to yet another swagger ui page this does look a little bit different than the weather bit api page but that's just because it's formatted differently using css behind the scenes it all is still just the swagger ui if i scroll down you can see here we have some notes on how to use it and also an authorized button that i can click here and i'll paste in my groov api key so that i can again test this right here in my browser to get the groove api key i just go back to my groove manage home page and select accounts you can use either an ldap user or a built-in groov manage user in this case i will use a group manage user the important thing is that you pick a system-wide administrator the reason for that is to use the groove manage api you do need admin permissions so make sure that your permissions do have a groovemanage admin set and copy and paste your api key so i'll grab that api key come over to swagger and i'll paste that in right here then when i click authorize we'll see that the padlock closes and we're all secure and we're authorized to test these api endpoints there's lots of things you can do here like reading and writing configuration getting your i o values and all sorts of different endpoints the one we're focusing on today though is this openvpn enable endpoint that we're going to post right here i'll just select this and select try it out you can see that there are no parameters i need to set since i've already put in my api key but we do need to set a request body that is required and that is just this json set right here you can see that it's expecting a json object with exactly one property and it has the name value and that should contain either true to enable or false to disable if you're not familiar with json formatting we have another video that goes in great depth as to how that works we'll have that linked in the description below but now that we've got that filled in already for us we do see that we're sending the value true so we should be enabling this openvpn client and you can see here that my tunnel is already configured i already have put in the vpn details and authorization that i need to be able to make this connection i just want to enable and disable it to connect and disconnect so i'll go ahead and click execute to send this value true object that'll go through you can see right away we get our ipv4 method has been set to automatic and we'll see in just a moment this will execute and there we go we get our response code of 200 we've already been signed an ip address on this subnet and in just a moment we'll see the link status switch to connected and we know that it's worked there it is goes to connect it we know that this has worked because we've got that response code of 200. again our swagger has given us the curl endpoint that we would need to hit if we were doing this via command line and the request url you'll note in this case for the groov manage api our authentication happens with this minus h this header right here where we're handing in one object and as the property name api key with the string of the api key handed in from there we also have this data object that we're handing in as well and that's that json object with the value property and that should be either true or false in this case we don't need to worry about this except or content type we'll just focus on the api key and the data body and this url of course so now let's take this post request and bring it into node-red so we can use node-red to enable and disable this vpn connection so i'll go ahead and i'll copy this request url bring that into my clipboard and come over to my node-red instance i'm going to paste this right here into the url right here you can see i have my openvpn enable endpoint right here but you'll also notice that the network i'm managing is on epicterry and my nodered instance is on epicterry so this is all happening on localhost so i can just type in localhost instead of my hostname i will use that same tls configuration because again i don't need to worry about certificates since my authentication is happening through that api key so with that set i'm good to go that's the endpoint i'm hitting but i will need to add an extra node in the middle here and so what i'm going to do is i'm going to do that with a function node and that is what's going to set my request body and my headers and i'm going to be doing this with a function node but if you're not familiar with javascript don't worry this is really light on code it's really straightforward to figure out exactly which properties i need to set i'll select the http request node and come over here to the help tab in this side panel here you can see i could set the url with message.url i could also set the method but the ones we want to focus on are message.headers which is going to be the http headers of the request and the message.payload and that's going to be the body of the request that's the data that we're sending to this endpoint so let's bring open this function node we're going to set meshes message.headers that's going to be equal to some object and we're also going to set our message.payload that's also going to be equal to an object so we're going to set these two values we'll hand them into the http request node and we'll be able to toggle our vpn tunnel so let's go back to the swagger ui we're going to grab this api key header copy that to the clipboard and we'll paste that into our headers right here you'll note that i don't have quotes around these but because they are strings i will need to add those again this is just standard json formatting so there we go i've put those in now we'll also need to set our payload and again that's this json pair here so i'll just select that make sure i grab the whole thing and copy that to my clipboard as well so here we go we've got our header set with that one property api key and the api key string and our message.payload which has that one property value which should contain true or false since it's already connected i'm going to change this to false so that we can disable it and show that this is working through node-red as well so with that set we're going to be injecting no properties are set but we're triggering this function node to set those properties that'll go into the http request and we'll be able to see the response here in our debug pane so let's go ahead and clear this up and we'll select deploy when i inject this will go through and run the flow and ah what's this we've got a status code 404 and we haven't disconnected something's gone wrong here and so i know that i have seen something go wrong because i've got this status code from the debug so before you put this thing actually into an application it's always a good idea to run through a couple of tests with debug nodes in so that you can make sure everything is being set correctly if something does go wrong you just need to go through the different parts of this http request to see what's wrong so we'll start at the top and we do know that our api key is correct we do have that correct property set and it is in a json pair same thing with the value we know that's correct we copied it exactly from the swagger ui so it must be something wrong with this http request and you can see what i've done wrong here even though i do have ssl and i do have the correct url i've left my method as get which was the default that i was using when i first put in the node and that i used to test the weatherbit api but if i come back to swagger here you can see that this endpoint is a post endpoint so it's important that each element of your http request all come together and match exactly what the swagger ui tells you to do so all i have to do is select this drop down change my method to post to match that swagger ui suggestion or not suggestion that swagger ui requirement i'll clear up my debug pane and deploy now when i inject it'll make that request i get back the status code of 200. you can see we've already lost our ip address and our ipv4 method has switched to disabled and there we go our link status has switched to disconnected so you can see how easy it is to take swagger ui bring that into node-red and create a really nice simple static example that can control your different api endpoints to take this just one step further i'm now going to make this dynamic because i may not want to just turn this off i may want to toggle it on for example if i need to reach out to a remote site to reconfigure something for example on my groov epic but i don't want to put it out on the internet or something like that i could create a secure vpn tunnel to my device get in there do the changes i need get back out and then disable the vpn and keep it all locked down safe and secure so to do that we of course need to be able to toggle it on and toggle it off true false messages and this could come from anywhere you could have something like a physical button press that enables and disables the vpn you could also pull something from a user interface like groov vue or node-red dashboard or even ignition you could even have something like another api or mqtt trigger it the main thing is is that you get a true false message into node-red and how do you format that to the http request node so let's check that out over here in the function node instead of just statically writing the value true or false i'm going to hand in a message property and because it's the openvpn enable i'm going to call it message.enable then enable will be true to enable it and message.enable will be false to disable it so i'll go ahead and make that change here and click done now all i need to do is inject that property so in this case it'll be message.enable and i want it to be a boolean value so i'll just select this drop-down click boolean and i'll inject true with this inject node and again this could be coming from anywhere but for the purposes of this example i'll just use this inject node i'll make a copy of that because i also need to inject false and we'll just double click that and reconfigure it to be false so our message.enable in this case is going to be false now i can inject true to enable it false to disable it it'll format it correctly and send it to the http request node let's double check these messages really quick to make sure that everything is coming through as expected so i'll get my input from the two injects that'll come up here to this top message debug node here and then we'll also have a one another one coming out of the function node clear my debug pane and click deploy and let's inject a true message so that we can see it enable this vpn tunnel i'll go ahead and inject true the request goes through and we see in just a moment there we go we've got our automatic ipv4 method and we'll get an ip address and connection shortly there we go so we can see here at the top we are sending our message.enable to be true then using this function node here we're wrapping that true false value into this json pair right here and now our payload instead of just being true or false our payload is an object it has the single property value and that contains either true or false then that goes through and triggers our http request node we know that it needs to be this object holding the property value because of course swagger tells us that so i can also inject false and disable it and we'll see that work in just a moment the important thing is that we're getting our status code 200 and this is now working dynamically we're not stuck to just true or false we're able to inject whatever message we want so i'll go ahead and inject false we'll see that it's going to be disabled there we go and in just a moment it'll be disconnected so you can see how easy it is to enable and disable our vpn connection tunnel just by following the swagger ui and this is just an example of one endpoint for one api but as long as you have swagger and node-red and you understand how to bring the two together you can control all sorts of different apis both getting and posting data using your node red flows if you have any questions we'll have some links in the description below that provide a lot of resources that cover some of the things i've sort of skimmed over in this video if you have any questions there's also the node red forums and our opto forums at forums.22.com i hope you found this video helpful and as always thanks for watching [Music] you

Channel: Opto Video

Views: 12,131

Keywords: automation, opto 22, opto, opto22, automatizacion y control industrial, groov, groov EPIC, groov RIO, opto 22 groov, IoT, IIoT, Opto programming, node-red, nodered, cybersecurity, swagger, swagger ui, api, api calls

Id: W-S_qlWjesg

Length: 18min 17sec (1097 seconds)

Published: Tue May 10 2022