1.4 to 2.0 Migration Tips

mcavage edited this page Jan 8, 2013 · 15 revisions

(the GH wiki eats this h1)

Trailing / characters

In 1.4, restify automatically "cleans up" the URL from something like //foo/////bar// to /foo/bar. This functionality is now optional for those that don't want that, but it means you as a user need to opt in like:

server.pre(restify.pre.sanitizePath());

"Hanging" requests with bodyParser and async handlers

This wasn't possible in 1.4 without a custom handler, but in restify 2, you probably want:

server.pre(restify.pre.pause());

CORS Headers disappeared

You need to use the "fullResponse" plugin: server.use(restify.fullResponse()), or see #284

restify.bunyan.serializers

Symptom: You might see the following error:

/opt/smartdc/imgapi/node_modules/bunyan/lib/bunyan.js:365
        throw new TypeError(format(
              ^
TypeError: invalid serializer for "res" field: must be a function
    at .../node_modules/bunyan/lib/bunyan.js:365:15
    at Array.forEach (native)
    at addSerializers (.../node_modules/bunyan/lib/bunyan.js:362:30)
    at new Logger (.../node_modules/bunyan/lib/bunyan.js:392:5)
    at Function.createLogger (.../node_modules/bunyan/lib/bunyan.js:1085:10)
    at handleArgv (.../main.js:120:18)
    at main (.../main.js:154:16)
    ...
    at Object.Module._extensions..js (module.js:467:10)

In restify 1.4 restify.bunyan.serializers includes a response field that you'd want to use like this:

var log = bunyan.createLogger({
  name: 'whatever',
  serializers: {
    res: restify.bunyan.serializers.response,
    req: bunyan.stdSerializers.req,
    err: bunyan.stdSerializers.err,
    ...
  },
  ...
});

In restify 2.0 the keys restify.bunyan.serializers actually match well-known log record field names (req for a request, res for a response). Also, restify includes more serializers (client_req and client_res are new) and re-exports the bunyan stdSerializers (at least the current set). Typical usage would now be:

var log = bunyan.createLogger({
  name: 'whatever',
  serializers: restify.bunyan.serializers,
  ...
});

Slightly less convenient if you have your own custom serializers, but generally a win.

req.path -> req.path() or req.getPath()

If you used req.path to check which of your endpoints was called, keep in mind that req.path is now a function and not a property in restify 2.0. This method is useful when you are sharing a pre (or post) function across different endpoint handlers and need to know what API action is being called.

In restify 2.0 req.path() is now a function:

function pre(req, res, next) {
    console.log(req.path());
    return next();
}

req.id -> req.getId() or req.id()

Similar to path above.

req.href -> req.getHref() or req.href()

Similar to path above.

req.query -> req.getQuery() or req.query()

Similar to path above.

X-* -> * for headers

Issue: https://github.com/mcavage/node-restify/issues/168

Specifically, these headers: X-Api-Version, X-Request-Id, and X-Response-Time

restify client err.httpCode -> err.statusCode

An error object from a restify client response (client_res) now looks like this:

{
  "message": "not found",
  "statusCode": 404,
  "body": {
    "code": "ResourceNotFound",
    "message": "not found"
  },
  "restCode": "ResourceNotFound",
  "name": "ResourceNotFoundError"
}

In restify 1.4 that statusCode was httpCode. I don't have a full restify 1.4 response error example handy.