Webinar: Making Connections using the remote.it API

Webinar: Making Connections using the remote.it API


My name is Gary Worsham I’m with remote.it support and today I’m going to be talking about how to make connections using the remote.it API here’s our agenda we’re gonna just have an overview of the API and when to use it and then the four steps shown here as far as what it takes to actually make a proxy connection with our API you’ll get the most out of this webinar if you know what remote it is and you’ve used remote.it you have familiarity with a REST API and you have some basic scripting experience using bash or the C shell in Linux including pipes, sed, awk, and grep so when should you use the remote.it connection API well, I’m going to show you something over here in the actual remote.it user interface whenever you go into our web portal and click on a service name to get a connection you are in fact using the remote.it API although it’s behind our web page and so you may choose to use the remote.it connection API if you’re writing your own application which needs to make remote.it connections or if you’re integrating remote connections into an existing application or ecosystem if you’re somewhat familiar with remote.it you’ll also understand that we support peer-to-peer connections also called p2p connections so the proxy or API based connection should be considered as a backup or failover for p2p connections which fail sometimes there are certain
network conditions where peer-to-peer connections will not work but proxy connections will also since peer-to-peer connections require a connectd daemon to be installed on the client if for whatever reason you’re unable to do that then can also use the API in order to make connections so the remote.it api lives at this address it’s a standard REST API using GET and POST messages you’ll see in the details as we get into them that you need to include your developer key most calls require a token and everything is encoded in JSON which is formatted text we’ll see quite a bit of that in just a few minutes the status response of each API call includes a key called “status” and if the value of the “status” key is true then the rest of the information is valid and can be used, but if it’s false, then you should look at the value of the key reason for an explanation of the failure and you should also deal with those
types of failure and error messages in your own code as you’re developing it and as I said before we’ll show some examples so here’s an overview of the workflow involved in making and using a proxy connection you start with the user login API endpoint and you supply this with your username, password, and developer key and this gives you a login token now, I’ve just shown the the login token here is pointing down here but as you can see it’s actually used in every subsequent API call also the developer key is used in all API calls but in any case, you first get the login token and give that to the /device/find/by/name/ along with the device or service name which you want to connect to and this will come back with some information including the device address now the device address is what the key is called in the JSON response this corresponds to the service ID in the web portal user interface once you get the device address you use that to make a proxy connection and the end result of this will be a proxy URL and proxy port sometimes in the general case along with a connection ID at this point when you get these things you’re able to use this information to make a connection whether it’s to an SSH server VNC, Samba whatever you have set up on your device and then finally when you’re done you will want to stop the connection and this turns off that particular proxy connection so that it’s no longer valid I’m just gonna go quickly here through the details of the various API’s which I’ve just discussed this is the login end point and one thing to know about login tokens is that they will expire after about 8 hours so, the code that you use should be able to anticipate an expired or invalid token and handle it appropriately whether you just want to fail or request that the person login again is up to your application the required input, as I said before, is the developer key and I’m going to show you where to get the developer key in the web portal over here on the left hand side you’ll click on this little arrow and it pops up a submenu then you can go to account and scroll down a bit and here’s your developer API key if you click on this button that will copy it to the clipboard and then you can put that into your own scripts and again, for the login
you need to supply username and password you need to supply username and password as you might expect this is an example using the curl command written in the shell programming language and this just shows the actual structure of a curl command including the expressions for the developer key and various other things that are required in order for this to succeed now this is appropriate if you’re programming in a shell language we also have at our website, at docs.remote.it we have examples for these API
endpoints in PHP, Python, node.js, and c-sharp and if you are developing in something other than those languages let us know if you can’t figure out how to use it typically modern languages will have some sort of calls for making HTTP
requests so that’s the sort of thing that you will use so moving right along, the user login will, when it gets valid input will respond and the actual response of the user login API endpoint includes much more information than this but what I’ve shown here are some of the important bits and especially the token which will be returned, that you’ll need to use and other possibilities could include an invalid key if you made a mistake in the developer key or incorrect password or username those would also come back in the response JSON next, the device/find/by/name API endpoint again, takes developer key and a token and then for the search parameters you’re going to put in the device name and the device name is actually the service name again, this is sort of a
terminology for up discrepancy that you’ll need to be aware of in the web portal we
refer to these things as services but the metadata that’s been defined refers to this as a device name so you put the actual name that you gave it when you set it up here and device state since we’re going to be trying to connect to it you’ll use active for the state and here’s the response that you might expect to a valid call to this API endpoint and part that’s important here is the device address and the device address is the same as the service ID which you’ll see here for each individual service so one thing I wanted to point out is that if you already know the service ID from the web UI if you happen to be
using that you can bypass this particular call but in the general case you don’t know the service ID unless you’ve memorized it it’s easier to refer to it by the service name and if you made a mistake in the setting up the search parameters you could get this error response finally once you have the service ID you’re going to want to make a proxy connection to a device here are some familiar things the developer key and the token and the device address which we just got from the previous call but also there’s a weight parameter here it says whether you want to wait for the
connection or not this should be set to true I think there was a legacy version where where you didn’t wait, but in general you will always want to wait for
the connection to become active before the call returns then the host IP field here is actually used in a feature which we call IP restriction and I want to show you over in the web portal if you’ve ever seen this at the bottom of the services dialog this is the same thing when I click this checkbox to say make public this disables the IP restriction and it’s controlling the value of this host IP parameter so let me talk a little bit more about IP
restriction first of all, as I said already the host IP parameter and the
device connect API call will enforce or relax IP restriction and the IP
restriction makes sure that the public and the IP restriction makes sure that the public IP address of the computer making the connection matches the IP which requested the connection and by the public IP address I mean the external IP address the IP address that you would get by going to whatismyip.com, for example and this host IP should be set to your public IP address to enforce IP restriction or it should be set to 0.0.0.0 to allow others to temporarily use this URL and port for connections if
desired so that’s the option in the web portal as I showed you before that makes this public and allows this to be shared for the life of the proxy now, connections on some mobile network at the client side especially will not succeed unless IP restriction is disabled as a technical issue with certain mobile networks so finally once we have the device address and again that sometimes referred to as a service I we can use the device connect API endpoint to actually make the proxy connection and there are two types of service endpoints, roughly speaking, I mean if you look at the menu you’ll see many types of protocols SSH, VNC, Samba, etc but fundamentally there are only two different types one is a reverse proxy and that is used by all web connections and one thing you’ll notice about
reverse proxies is that they only have a host URL and there is no port on here because reverse proxies for web servers do not do port re-mapping whereas, the response from port proxy which is used by all non web connections such as SSH, VNC, RDP, etc includes the remap port so here the proxy includes a part which is a proxy server in your geographic region and also a randomized port over here which is between 30,000 and 40,000 other possible responses to device connect could include message that the device is not active it’s offline which could happen possibly, if it went offline after you got the service ID or device address for some reason the device is not owned by this account that would probably happen if you made a mistake in the service ID or did something like transferred it to somebody else after you got it so I guess there’s a variety of fairly rare edge cases where that could happen or you happen to be using an expired login token and the login token is generally valid for approximately eight hours now it could expire sooner than that or it could be valid for longer than that so in the code that you write you should anticipate the possibility of an expired login token so once you’re done using
the proxy connection you terminate the proxy connection by using this call and again you need the developer key and login token and then you also need the device address and the connection ID which came
from the previous call and on a valid call to this API endpoint this will be the response you’ll get a status of true and the connection ID will be
the connection ID that you sent it and other possibilities could be various error messages and you will see that shown here under the the reason in the
case that status comes back as false so I’m going to show you some examples using gel scripting and these they’re just to show you the most simple way of
using the API’s in a shell script and if you’re not familiar with JSON it’s not necessarily, in fact not at all it’s not designed to be read by human beings even though it is text but it’s a bunch of formatted and key value pairs that are all jammed together on one line so just for the purposes of this demonstration I’m going to be using the sed, grep, and awk functions here to show you how I can filter out the things that I’m interested in looking for and if you are writing shell scripts you can actually use the same approach or if you’re using a higher level programming language like any of the ones that I mentioned generally these will include much more flexible and powerful libraries that allow you to do easier JSON parsing so so I’m gonna go over here to a terminal and in this case I’m actually running the ubuntu subsystem of Windows 10 but this exact same thing should work fine on a mac OS terminal or on a Raspberry Pi or on an actual Linux PC of some sort and I’ve written some scripts here to demonstrate these API’s so the first one is the log in I’ll just show you what this consists of this is a script I’ve identified these variables or constants that’s my developer key that is my user name and that’s my password and and this is a temporary account that I’m using for this demo so I’m not really giving anything away by showing you this and this is the command
you saw earlier that will come back with my login token so let me just run that and I’ll show you what happens okay this is an example of some JSON that came back and as you can see that’s pretty difficult but what I’ll do is, I will look like I said before, I’ll pipe it through sed, and I will replace commas with back slashes and that will put one key value pair on each line and then since I’m looking for a token I’ll use the grep function to find the token and there are several keys that include the word “token” “token”, “token_index”, “service_token” and “auth_token” you can actually see the “token” and “auth_token” are the same thing so you can use either one of those in this case and that will put into the subsequent API calls okay so the next API call I’m going to make is a device/find/by/name so I will show you what is in that one and again I have the token and the dev key and then also the device name and I prearranged this just so that would be quicker to show you so let me type this one in we’ll see what happens okay, so this is the JSON that comes back for device/find/by/name I’m going to do the same trick I did before which is to filter it through sed okay so that’s one key value pair per
line I’m gonna filter again using grep on device address which I know is what I’m looking for I don’t know why that keeps happening okay so in fact I got I got two matches
here and I’m not, if you were actually doing this in shell scripting
language then of course you would need to refine this a little bit using some other commands just to get that down to the single response and I’ve already got
this device address in my next call which is the device connect call sorry I should have showed you what it was first I’ll just I’ll make a connection let me just start that over, im sorry so I’m going to show you the device connect script and again we have token, developer key, the actual device address, and host IP which I have put to 0.0.0.0 just to not have any trouble with IP restriction this is the structure of the curl call so I’ve already made the device connect API call above here and I’m going to again run that through my little sed filter and I’m gonna search for a proxy because I happen to know that some of the metadata that I’m looking for whoops sorry I should have said pipe grep proxy oh dear oh dear let me just see what what I’m doing
wrong oh oh alright I should I’m getting confused here doing things out of order alright first thing and then I will send that to grip and this comes back with the proxy which is the fully formed URL and port combined and then we
also have proxy port and proxy server since I know that this is an SSH
endpoint and it’s a Raspberry Pi I’m gonna use this information to log in SSH
– L pi and then proxy 18 dot R T 3 dot i o – p for the port lowercase P 3 9 7 – 6
and this is making a proxy connection in my Raspberry Pi I’ll type in the
password and now I’m on my Raspberry Pi and I can
do whatever I would normally do on my Raspberry Pi now the next thing I’m
going to do I’m going to just back up a little bit because you remember I said
that when I terminate a proxy connection I need to use the connection ID so that
that came out up here I’m just going to copy this okay and I’ll just do some things over here on
the pie that one might do to see that it really is a Raspberry Pi that I’m on
right now okay so I’ve done everything I want to on my Raspberry Pi so I’m going
to exit out of the connection now the proxy connection is still active and if
I want to use it again I can go ahead and use it again and until such time
that it expires which similar to the login token could be up to eight hours
I’m actually not going to do that at this time what I am going to do is I’m
going to edit the device connect stop script and I’m going to replace this
connection ID because that was for the previous demo we did with with this one
that we just created okay so now I’m going to run this and that comes back with a status of
true and then the ID which just matches the same connection ID that we gave it
before and what you’ll notice now is that when I attempt to use this proxy
connection that it is refused it’s it’s no longer valid which is exactly what we
wanted now if your proxy expires the same thing will happen so that’s the
sort of thing that you’ll need to check for when you’re actually using it and if
and if this happens and you weren’t expecting and it’s probably the case
that the proxy itself has expired so at this point I’m gonna open it up
for questions looks like a question has come in are there any negative
ramifications to not terminating the proxy connection well if the first of
all the proxy connection will stay open for a number of hours and if you don’t
terminate it and you also made it public or relaxed IP restriction I suppose that
there’s a possibility that somebody who wasn’t supposed to could connect to it
so if you use IP restriction that becomes really exceedingly unlikely but
those are the theoretical ramifications of not terminating the proxy connection
so we do recommend that when you’re using the API that you do terminate the
proxy connection is there an API to run a bulk script
this is a very common request and at this point we do not have a publicly
usable API to run a bulk scrip however that is pretty high up on our list of
things to implement so the people can use it
how long is the proxy address valid and it is valid for about eight hours and
like I said before you should in your code count for all possible conditions
including an expired proxy so you’re not confused when perhaps things don’t work
when you think they should in fact we do have some stuff that’s in
development right now which is actually a different approach to querying the
databases through the api’s I can’t talk much about it right now but the answer
is definitely yes we’re planning on adding more API endpoints and abilities
to do things more efficiently rather than downloading the entire device list
which we understand is a little time consuming and slow and clunky once you
get you know several thousand services in there pose I want to use the api’s in some
kind of a cross-platform applications such as Mac Windows Android iOS is that
possible well the answer is yes however it does depend on your ability to add
for example at just if the basic shell command level you need curl with SSL
support and you should also have CA certificates installed so that we can
support SSL a secure socket layer properly communication back to the API
server there’s a way to force it not to check certificates but we don’t really
recommend that for a production solution you could do that in evaluation also if
you’re not using curl necessarily as I mentioned before many of the higher
level languages do include HTTP request libraries and you would want to use
those along with the CA certificates so that you have SSL supported for those
API and calls is there an API call to get all open
connections to be closed it’s a good question I’m unaware of any such API
called so if you’re going to be managing connections then you’ll probably want to
keep track of those connections in a list and then when you want to clean up
go through that and blows them all I will also take this question back to
engineering to see if maybe there’s something that I am unaware of and we’ll
get that into the notes you are correct the device find by name
API endpoint has not yet documented if the dock start remote it I am going to
have to add that after I get done with this webinar so at this point the
documentation is in these slides which we can send to you when we’re done
and I will also put it up at the dock site so here’s
additional resources you can access which I hope you will find useful for
learning about remote in general and the api’s this is all of our general purpose
information you should also check out our YouTube channel because there are
some videos there about making p2p connections which you should also know
about some links directly into information
about the remoted API peer-to-peer versus proxy connections and making
peer-to-peer connections and if you have any questions whether they’re just
theoretical or if you’re having a problem trying to implement something
with the API I do hope that you will reach out and ask those questions
because we are here to try to help you use the product thanks again bye-bye you

Leave a Reply

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