Restify — Versioned Routes and Upgrade Requests

Restify is a simple Node back end framework.

In this article, we’ll look at how to add routes with Restify.

Versioned Routes

Restify routes can be versioned.

The version number should follow semantic versioning.

For example, we can write:

var restify = require('restify');

var server = restify.createServer();

function sendV1(req, res, next) {
  res.send(`hello: ${req.params.name}`);
  return next();
}

function sendV2(req, res, next) {
  res.send({ hello: req.params.name });
  return next();
}

server.get('/hello/:name', restify.plugins.conditionalHandler([
  { version: '1.1.3', handler: sendV1 },
  { version: '2.0.0', handler: sendV2 }
]));

server.listen(8080);

to have different versions of a route.

Then we can make a request with the accept-version header with the version number as a value.

If this header isn’t provided, then the handler for the latest version will be run.

For example, if we run:

curl -s localhost:8080/hello/foo

We get:

{
    "hello": "foo"
}

And if we run:

curl -s -H 'accept-version: ~1' localhost:8080/hello/foo

We get:

"hello: foo"

And if we run:

curl -s -H 'accept-version: ~2' localhost:8080/hello/foo

We get:

{
    "hello": "foo"
}

If we have an invalid version number in our header like:

curl -s -H 'accept-version: ~3' localhost:8080/hello/foo

We get:

{
    "code": "InvalidVersion",
    "message": "~3 is not supported by GET /hello/foo"
}

We can use the same route handlers for multiple versions by passing in an array:

var restify = require('restify');

var server = restify.createServer();

function sendV1(req, res, next) {
  res.send(`hello: ${req.params.name}`);
  return next();
}

function sendV2(req, res, next) {
  res.send({ hello: req.params.name });
  return next();
}

server.get('/hello/:name', restify.plugins.conditionalHandler([
  { version: '1.1.3', handler: sendV1 },
  { version: ['2.0.0', '2.1.0', '2.2.0'], handler: sendV2 }
]));

server.listen(8080);

Also, we can get the original requested version with the req.version method.

And we can get the version that’s matched by Restify with the matchedVersion method.

For example, we can write:

var restify = require('restify');

var server = restify.createServer();

server.get('/hello/:name', restify.plugins.conditionalHandler([
 {
    version: ['2.0.0', '2.1.0', '2.2.0'],
    handler: function (req, res, next) {
      res.send(200, {
        requestedVersion: req.version(),
        matchedVersion: req.matchedVersion()
      });
      return next();
    }
  }
]));

server.listen(8080);

Then if we run:

curl -s -H 'accept-version: ~2' localhost:8080/hello/foo

We get:

{
    "requestedVersion": "~2",
    "matchedVersion": "2.2.0"
}

Upgrade Requests

If an incoming HTTP requests that has the Connection: Upgrade header, then it’s treated differently by the Node server.

It won’t be pushed through to Restify by default.

We can make this pushed through with the handleUpgrades option.

For example, we can write:

var restify = require('restify');
var Watershed = require('Watershed');

var server = restify.createServer();

var ws = new Watershed();
server.get('/websocket/attach', function(req, res, next) {
  if (!res.claimUpgrade) {
    next(new Error('Connection Must Upgrade For WebSockets'));
    return;
  }

var upgrade = res.claimUpgrade();
  var shed = ws.accept(req, upgrade.socket, upgrade.head);
  shed.on('text', function(msg) {
    console.log('Received message from websocket client: ' + msg);
  });
  shed.send('hello there!');

  next(false);
});

server.listen(8080);

We create the Watershed instance to listen for WebSockets connection.

Conclusion

We can version our routes with Restify.

Also, we can use Watershed to handle Webscoket requests.