Introduction

This walk-through is to show you how to make client requests to the Xirsys V3.0 REST API using a secure method. You will learn how to use a Node/Express application to serve static web files and securely make requests on behalf of the client/browser.

Prerequisites

  • Knowledge of how to generate a self-signed cert
  • Basic understanding of Node.js and how to set up a web accessible server
  • General understanding of Express and how it routes HTTP communication
  • Xirsys account with a channel created (Please refer to the Getting Started docs for help creating a channel.)
  • Getting Started

    You will first need to download the Xirsys Examples repo if you haven’t already. And you will need to install Node.js if you do not already have it installed. Notice the Node dependencies are defined in the package.json in the Examples repo. The Node dependencies can be installed using the Node Package Manager, also known as NPM.

    nodedependencies

    Creating HTTP and HTTPS Servers

    The HTTP and HTTPS servers are created in the server.js file, which passes along the Express application which will function as our request listener.

    We recommend all calls to the Xirsys API be made over HTTPS, which is why we redirect every call made to our Node server to the HTTPS service.

    Serving Static Files with Express

    As a request listener, the Express app will serve as a static web host and work as a proxy to the Xirsys RESTful API. The Express application (index.js) resides in the App directory and express.static, which is a built-in middleware function within the index.js file, enables the serving of static files.

    Since the express.static function passed a namespace of “public”, we must create the directory within the App directory.

    app_public_dir

    Setting Up A Router To Handle Secure RESTful Requests

    We need to set up the proxy that will properly route the requests made to the Xirsys RESTful API. You’ll notice the Routes directory where our webrtc.js class resides. The webrtc.js class will return an express.Router.

    The router is then defined within the Express application (index.js).

    Notice we pass along the Xirsys config JSON object to the webrtc route so that it will correctly handle the proxied requests to the Xirsys API.

    The class/router will catch any ‘webrtc’ client requests made to the API, validate the request, and if needed, modify the inbound request by appending the channel name to the path of the Xirsys request, and then finally a secure request is made on behalf of the client to the Xirsys API.

    Apply Your Xirsys Account Info

    Now that you understand how this sample will securely make calls to the Xirsys API and have Node and all your files set up, you can test it with your own Xirsys account. Since we’re using the Node dependency “config”, we can centralize the Xirsys information our app will require within a default configuration file, named default.json. Open the default.json file in your Config folder and enter your Xirsys account details. Displayed below is the structure the application uses to properly inject the relevant Xirsys information, you are going to replace the ident, secret and channel parameters with your account values, then save the file.

    Let’s Test!

    Open a terminal window or command prompt, and navigate to your project directory then start the Node application (run node server.js). As a reminder, you will need to be sure the Node dependencies have been installed first, before starting Node, see Getting Started above. Only once the Node application is running and has created our web servers, can we navigate to any file residing within the Public directory. Navigate to your Xirsys Examples folder:

    https://localhost:3443/[File name]

    If everything has been set up properly, you should see this main examples page:

    The endpoint used to proxy the Xirsys requests should resemble the following path:

    https://localhost:3443/webrtc/[XIRSYS METHOD]

    Please refer to the Xirsys API Doc for definitions of the Xirsys requests made via the proxy.

    Secure Your Application

    Now that you have your secure proxy set up to make calls to the API, you can apply this to your application. We’ll use our webrtc_chat demo as an example of how to do this. We need to just make sure the server path used by the application is pointing to our proxy and define that path within the xirsys_connect.js file as shown below:

    Navigate in your browser to the webrtc_chat in your Xirsys Examples, and you should be able to make a video call:

    Conclusion

    Now you can see how to communicate SECURELY with the Xirsys V3.0 REST API by setting up a middle layer to communicate with the Xirsys API. We created an HTTP and HTTPS server using Node.js and Express.js to not only host publicly accessible static files, but also to securely proxy requests to the Xirsys 3.0 REST API.