Introduction

This walk-through will show you how to make client requests to the Xirsys V3.0 REST API using an unsecure method. You will learn how to construct a signaling URL and retrieve a list of available TURN and STUN servers using jQuery AJAX.

Please note this method is for testing and learning purposes only and should not be used in production, as you will want to secure your credentials and token to avoid compromising your account. To secure your account, please see this example.

Prerequisites

  • Download this file for this tutorial, and you will need to host this on a secure (https) webserver: ice_signaling
  • You need a Xirsys account with a channel created (Please refer to the Getting Started docs for help creating a channel.)

Getting Started

Open the index.html file you just downloaded and you will notice the jQuery AJAX calls to the Xirsys API start on line 34, this is what we’re going to be walking through. If you would like to just start testing, you can skip to the bottom of this tutorial to ‘Applying your Xirsys Account Info’.

Defining The Methods And Requests Made To The RESTful API

Let’s go through the methods and the requests made to the Xirsys RESTful API. Here are the methods we will be using:

getHost

First up is the “getHost” method. In order for clients to connect to one another over WebRTC, there has to be a way for a client to find and contact another client. Currently, we do this via a signaling request over websockets. We must first compile the signaling URL our websocket will use to find and contact other clients. The getHost method will request the signaling/websocket URL for the least loaded server on the cluster located closest to the client. To find the client’s optimal signaling URL, the channel must be added to the path, and the key and type parameters must be appended as a query string.

getToken

Next is the “getToken” method. This request to the Xirsys REST API returns a token, and when combined with the signaling URL, allows a given client to connect to our websocket signal servers for a specific channel. Be sure to include the same key parameter value passed when requesting the signaling host. You may also want to send along the expire parameter, which defines the duration a token is valid in seconds. The default expiration for the token is 60 seconds, but you can set this value to anything you would like or set it to never expire, please see the docs for more information on this.

getTurn

Finally, we have the “getTurn” method. This method simply retrieves an ICE string, or list of iceServers, consisting of both STUN and TURN servers. With a list of both STUN and TURN servers, the client will be able to select the means by which they wish to establish their peer connection.

Applying Your Xirsys Account Info

Now that you understand the requests we will be making to the Xirsys API, let’s add your credentials so you can test this out. You will see there is a config object variable on line 39 that looks like this:

This is where you will apply your Xirsys credentials. You will need to get your ident, secret (API token) and channel from your Xirsys dashboard.

dashboard

Let’s Test!

Now that you have added your credentials and have this file hosted on a secure server, you can open the index.html file in your browser and run the sample. If everything has been set up properly, you should get something like this, that shows a list of Stun/Turn servers as well as a signaling URL:

Xirsys demo URLs

Conclusion

In this tutorial, we demonstrated how you can use jQuery AJAX to communicate UNSECURELY with the Xirsys 3.0 REST API. Now that you have an understanding of the basic calls needed to get started with our service and make WebRTC connections, you will want to be sure to secure your credentials and token, please see our tutorial here for help with securing your account. Or if you have already secured your account, then you can view this tutorial on integrating these calls into your application.