--- title: Server API permalink: /docs/server-api/ --- ### Table of Contents - [createServer][1] - [Server][2] - [listen][3] - [close][4] - [get][5] - [head][6] - [post][7] - [put][8] - [patch][9] - [del][10] - [opts][11] - [pre][12] - [use][13] - [param][14] - [rm][15] - [address][16] - [inflightRequests][17] - [debugInfo][18] - [toString][19] - [Events][20] - [Errors][21] - [Types][22] - [Server~methodOpts][23] ## createServer A restify server object is the main interface through which you will register routes and handlers for incoming requests. **Parameters** - `options` **[Object][24]?** an options object - `options.name` **[String][25]** Name of the server. (optional, default `"restify"`) - `options.dtrace` **[Boolean][26]** enable DTrace support (optional, default `false`) - `options.router` **Router** Router (optional, default `newRouter(opts)`) - `options.log` **[Object][24]** [bunyan][27] instance. (optional, default `bunyan.createLogger(options.name||"restify")`) - `options.url` **[String][25]?** Once listen() is called, this will be filled in with where the server is running. - `options.certificate` **([String][25] \| [Buffer][28])?** If you want to create an HTTPS server, pass in a PEM-encoded certificate and key. - `options.key` **([String][25] \| [Buffer][28])?** If you want to create an HTTPS server, pass in a PEM-encoded certificate and key. - `options.formatters` **[Object][24]?** Custom response formatters for `res.send()`. - `options.handleUncaughtExceptions` **[Boolean][26]** When true restify will use a domain to catch and respond to any uncaught exceptions that occur in its handler stack. Comes with significant negative performance impact. (optional, default `false`) - `options.spdy` **[Object][24]?** Any options accepted by [node-spdy][29]. - `options.http2` **[Object][24]?** Any options accepted by [http2.createSecureServer][30]. - `options.handleUpgrades` **[Boolean][26]** Hook the `upgrade` event from the node HTTP server, pushing `Connection: Upgrade` requests through the regular request handling chain. (optional, default `false`) - `options.onceNext` **[Boolean][26]** Prevents calling next multiple times (optional, default `false`) - `options.strictNext` **[Boolean][26]** Throws error when next() is called more than once, enabled onceNext option (optional, default `false`) - `options.httpsServerOptions` **[Object][24]?** Any options accepted by [node-https Server][31]. If provided the following restify server options will be ignored: spdy, ca, certificate, key, passphrase, rejectUnauthorized, requestCert and ciphers; however these can all be specified on httpsServerOptions. - `options.noWriteContinue` **[Boolean][26]** prevents `res.writeContinue()` in `server.on('checkContinue')` when proxing (optional, default `false`) - `options.ignoreTrailingSlash` **[Boolean][26]** ignore trailing slash on paths (optional, default `false`) - `options.strictFormatters` **[Boolean][26]** enables strict formatters behavior: a formatter matching the response's content-type is required. If not found, the response's content-type is automatically set to 'application/octet-stream'. If a formatter for that content-type is not found, sending the response errors. (optional, default `true`) **Examples** ```javascript var restify = require('restify'); var server = restify.createServer(); server.listen(8080, function () { console.log('ready on %s', server.url); }); ``` Returns **[Server][32]** server ## Server Creates a new Server. **Parameters** - `options` **[Object][24]** an options object - `options.name` **[String][25]** Name of the server. - `options.dtrace` **[Boolean][26]** enable DTrace support (optional, default `false`) - `options.router` **Router** Router - `options.log` **[Object][24]** [bunyan][27] instance. - `options.url` **[String][25]?** Once listen() is called, this will be filled in with where the server is running. - `options.certificate` **([String][25] \| [Buffer][28])?** If you want to create an HTTPS server, pass in a PEM-encoded certificate and key. - `options.key` **([String][25] \| [Buffer][28])?** If you want to create an HTTPS server, pass in a PEM-encoded certificate and key. - `options.formatters` **[Object][24]?** Custom response formatters for `res.send()`. - `options.handleUncaughtExceptions` **[Boolean][26]** When true restify will use a domain to catch and respond to any uncaught exceptions that occur in its handler stack. Comes with significant negative performance impact. - `options.spdy` **[Object][24]?** Any options accepted by [node-spdy][29]. - `options.http2` **[Object][24]?** Any options accepted by [http2.createSecureServer][30]. - `options.handleUpgrades` **[Boolean][26]** Hook the `upgrade` event from the node HTTP server, pushing `Connection: Upgrade` requests through the regular request handling chain. (optional, default `false`) - `options.onceNext` **[Boolean][26]** Prevents calling next multiple times (optional, default `false`) - `options.strictNext` **[Boolean][26]** Throws error when next() is called more than once, enabled onceNext option (optional, default `false`) - `options.httpsServerOptions` **[Object][24]?** Any options accepted by [node-https Server][31]. If provided the following restify server options will be ignored: spdy, ca, certificate, key, passphrase, rejectUnauthorized, requestCert and ciphers; however these can all be specified on httpsServerOptions. - `options.noWriteContinue` **[Boolean][26]** prevents `res.writeContinue()` in `server.on('checkContinue')` when proxing (optional, default `false`) - `options.ignoreTrailingSlash` **[Boolean][26]** ignore trailing slash on paths (optional, default `false`) - `options.strictFormatters` **[Boolean][26]** enables strict formatters behavior: a formatter matching the response's content-type is required. If not found, the response's content-type is automatically set to 'application/octet-stream'. If a formatter for that content-type is not found, sending the response errors. (optional, default `true`) **Examples** ```javascript var restify = require('restify'); var server = restify.createServer(); server.listen(8080, function () { console.log('ready on %s', server.url); }); ``` ### listen Gets the server up and listening. Wraps node's [listen()][33]. **Parameters** - `port` **[Number][34]** Port - `host` **[Number][34]?** Host - `callback` **[Function][35]?** optionally get notified when listening. **Examples** You can call like: ```javascript server.listen(80) server.listen(80, '127.0.0.1') server.listen('/tmp/server.sock') ``` - Throws **[TypeError][36]** Returns **[undefined][37]** no return value ### close Shuts down this server, and invokes callback (optionally) when done. Wraps node's [close()][38]. **Parameters** - `callback` **[Function][35]?** callback to invoke when done Returns **[undefined][37]** no return value ### get Mounts a chain on the given path against this HTTP verb **Parameters** - `opts` **[Server~methodOpts][39]** if string, the URL to handle. if options, the URL to handle, at minimum. **Examples** ```javascript server.get('/', function (req, res, next) { res.send({ hello: 'world' }); next(); }); ``` Returns **Route** the newly created route. ### head Mounts a chain on the given path against this HTTP verb **Parameters** - `opts` **[Server~methodOpts][39]** if string, the URL to handle. if options, the URL to handle, at minimum. Returns **Route** the newly created route. ### post Mounts a chain on the given path against this HTTP verb **Parameters** - `post` **[Server~methodOpts][39]** if string, the URL to handle. if options, the URL to handle, at minimum. Returns **Route** the newly created route. ### put Mounts a chain on the given path against this HTTP verb **Parameters** - `put` **[Server~methodOpts][39]** if string, the URL to handle. if options, the URL to handle, at minimum. Returns **Route** the newly created route. ### patch Mounts a chain on the given path against this HTTP verb **Parameters** - `patch` **[Server~methodOpts][39]** if string, the URL to handle. if options, the URL to handle, at minimum. Returns **Route** the newly created route. ### del Mounts a chain on the given path against this HTTP verb **Parameters** - `opts` **[Server~methodOpts][39]** if string, the URL to handle. if options, the URL to handle, at minimum. Returns **Route** the newly created route. ### opts Mounts a chain on the given path against this HTTP verb **Parameters** - `opts` **[Server~methodOpts][39]** if string, the URL to handle. if options, the URL to handle, at minimum. Returns **Route** the newly created route. ### pre Gives you hooks to run _before_ any routes are located. This gives you a chance to intercept the request and change headers, etc., that routing depends on. Note that req.params will _not_ be set yet. **Parameters** - `handler` **...([Function][35] \| [Array][40])** Allows you to add handlers that run for all routes. _before_ routing occurs. This gives you a hook to change request headers and the like if you need to. Note that `req.params` will be undefined, as that's filled in _after_ routing. Takes a function, or an array of functions. variable number of nested arrays of handler functions **Examples** ```javascript server.pre(function(req, res, next) { req.headers.accept = 'application/json'; return next(); }); ``` For example, `pre()` can be used to deduplicate slashes in URLs ```javascript server.pre(restify.pre.dedupeSlashes()); ``` Returns **[Object][24]** returns self ### use Allows you to add in handlers that run for all routes. Note that handlers added via `use()` will run only after the router has found a matching route. If no match is found, these handlers will never run. Takes a function, or an array of functions. You can pass in any combination of functions or array of functions. **Parameters** - `handler` **...([Function][35] \| [Array][40])** A variable number of handler functions- and/or a variable number of nested arrays of handler functions Returns **[Object][24]** returns self ### param - **See: [http://expressjs.com/guide.html#route-param%20pre-conditions][41]** Minimal port of the functionality offered by Express.js Route Param Pre-conditions This basically piggy-backs on the `server.use` method. It attaches a new middleware function that only fires if the specified parameter exists in req.params Exposes an API: server.param("user", function (req, res, next) { // load the user's information here, always making sure to call next() }); **Parameters** - `name` **[String][25]** The name of the URL param to respond to - `fn` **[Function][35]** The middleware function to execute Returns **[Object][24]** returns self ### rm Removes a route from the server. You pass in the route 'blob' you got from a mount call. **Parameters** - `routeName` **[String][25]** the route name. - Throws **[TypeError][36]** on bad input. Returns **[Boolean][26]** true if route was removed, false if not. ### address Returns the server address. Wraps node's [address()][42]. **Examples** ```javascript server.address() ``` Output: ```javascript { address: '::', family: 'IPv6', port: 8080 } ``` Returns **[Object][24]** Address of server ### inflightRequests Returns the number of inflight requests currently being handled by the server Returns **[number][34]** number of inflight requests ### debugInfo Return debug information about the server. **Examples** ```javascript server.getDebugInfo() ``` Output: ```javascript { routes: [ { name: 'get', method: 'get', input: '/', compiledRegex: /^[\/]*$/, compiledUrlParams: null, handlers: [Array] } ], server: { formatters: { 'application/javascript': [Function: formatJSONP], 'application/json': [Function: formatJSON], 'text/plain': [Function: formatText], 'application/octet-stream': [Function: formatBinary] }, address: '::', port: 8080, inflightRequests: 0, pre: [], use: [ 'parseQueryString', '_jsonp' ], after: [] } } ``` Returns **[Object][24]** debug info ### toString toString() the server for easy reading/output. **Examples** ```javascript server.toString() ``` Output: ```javascript Accepts: application/json, text/plain, application/octet-stream, application/javascript Name: restify Pre: [] Router: RestifyRouter: DELETE: [] GET: [get] HEAD: [] OPTIONS: [] PATCH: [] POST: [] PUT: [] Routes: get: [parseQueryString, _jsonp, function] Secure: false Url: http://[::]:8080 Version: ``` Returns **[String][25]** stringified server ## Events In additional to emitting all the events from node's [http.Server][43], restify servers also emit a number of additional events that make building REST and web applications much easier. ### restifyError This event is emitted following all error events as a generic catch all. It is recommended to use specific error events to handle specific errors, but this event can be useful for metrics or logging. If you use this in conjunction with other error events, the most specific event will be fired first, followed by this one: ```js server.get('/', function(req, res, next) { return next(new InternalServerError('boom')); }); server.on('InternalServer', function(req, res, err, callback) { // this will get fired first, as it's the most relevant listener return callback(); }); server.on('restifyError', function(req, res, err, callback) { // this is fired second. return callback(); }); ``` ### after After each request has been fully serviced, an `after` event is fired. This event can be hooked into to handle audit logs and other metrics. Note that flushing a response does not necessarily correspond with an `after` event. restify considers a request to be fully serviced when either: 1) The handler chain for a route has been fully completed 2) An error was returned to `next()`, and the corresponding error events have been fired for that error type The signature is for the after event is as follows: ```js function(req, res, route, error) { } ``` - `req` - the request object - `res` - the response object - `route` - the route object that serviced the request - `error` - the error passed to `next()`, if applicable Note that when the server automatically responds with a NotFound/MethodNotAllowed/VersionNotAllowed, this event will still be fired. ### pre Before each request has been routed, a `pre` event is fired. This event can be hooked into handle audit logs and other metrics. Since this event fires _before_ routing has occured, it will fire regardless of whether the route is supported or not, e.g. requests that result in a `404`. The signature for the `pre` event is as follows: ```js function(req, res) {} ``` - `req` - the request object - `res` - the response object Note that when the server automatically responds with a NotFound/MethodNotAllowed/VersionNotAllowed, this event will still be fired. ### routed A `routed` event is fired after a request has been routed by the router, but before handlers specific to that route has run. The signature for the `routed` event is as follows: ```js function(req, res, route) {} ``` - `req` - the request object - `res` - the response object - `route` - the route object that serviced the request Note that this event will _not_ fire if a requests comes in that are not routable, i.e. one that would result in a `404`. ### uncaughtException If the restify server was created with `handleUncaughtExceptions: true`, restify will leverage [domains][44] to handle thrown errors in the handler chain. Thrown errors are a result of an explicit `throw` statement, or as a result of programmer errors like a typo or a null ref. These thrown errors are caught by the domain, and will be emitted via this event. For example: ```js server.get('/', function(req, res, next) { res.send(x); // this will cause a ReferenceError return next(); }); server.on('uncaughtException', function(req, res, route, err) { // this event will be fired, with the error object from above: // ReferenceError: x is not defined }); ``` If you listen to this event, you **must** send a response to the client. This behavior is different from the standard error events. If you do not listen to this event, restify's default behavior is to call `res.send()` with the error that was thrown. The signature is for the after event is as follows: ```js function(req, res, route, error) { } ``` - `req` - the request object - `res` - the response object - `route` - the route object that serviced the request - `error` - the error passed to `next()`, if applicable ### close Emitted when the server closes. ## Errors Restify handles errors as first class citizens. When an error object is passed to the `next()` function, an event is emitted on the server object, and the error object will be serialized and sent to the client. An error object is any object that passes an `instanceof Error` check. Before the error object is sent to the client, the server will fire an event using the name of the error, without the `Error` part of the name. For example, given an `InternalServerError`, the server will emit an `InternalServer` event. This creates opportunities to do logging, metrics, or payload mutation based on the type of error. For example: ```js var errs = require('restify-errors'); server.get('/', function(req, res, next) { return next(new errs.InternalServerError('boom!')); }); server.on('InternalServer', function(req, res, err, callback) { // before the response is sent, this listener will be invoked, allowing // opportunities to do metrics capturing or logging. myMetrics.capture(err); // invoke the callback to complete your work, and the server will send out // a response. return callback(); }); ``` Inside the error event listener, it is also possible to change the serialization method of the error if desired. To do so, simply implement a custom `toString()` or `toJSON()`. Depending on the content-type and formatter being used for the response, one of the two serializers will be used. For example, given the folllwing example: ```js server.on('restifyError', function(req, res, err, callback) { err.toJSON = function customToJSON() { return { name: err.name, message: err.message }; }; err.toString = function customToString() { return 'i just want a string'; }; return callback(); }); ``` A request with an `accept: application/json` will trigger the `toJSON()` serializer, while a request with `accept: text/plain` will trigger the `toString()` serializer. Note that the function signature for the error listener is identical for all emitted error events. The signature is as follows: ```js function(req, res, err, callback) { } ``` - `req` - the request object - `res` - the response object - `err` - the error object - `callback` - a callback function to invoke When using this feature in conjunction with [restify-errors][45], restify will emit events for all of the basic http errors: - `400` - `BadRequestError` - `401` - `UnauthorizedError` - `402` - `PaymentRequiredError` - `403` - `ForbiddenError` - `404` - `NotFoundError` - `405` - `MethodNotAllowedError` - `406` - `NotAcceptableError` - `407` - `ProxyAuthenticationRequiredError` - `408` - `RequestTimeoutError` - `409` - `ConflictError` - `410` - `GoneError` - `411` - `LengthRequiredError` - `412` - `PreconditionFailedError` - `413` - `RequestEntityTooLargeError` - `414` - `RequesturiTooLargeError` - `415` - `UnsupportedMediaTypeError` - `416` - `RangeNotSatisfiableError` (node >= 4) - `416` - `RequestedRangeNotSatisfiableError` (node 0.x) - `417` - `ExpectationFailedError` - `418` - `ImATeapotError` - `422` - `UnprocessableEntityError` - `423` - `LockedError` - `424` - `FailedDependencyError` - `425` - `UnorderedCollectionError` - `426` - `UpgradeRequiredError` - `428` - `PreconditionRequiredError` - `429` - `TooManyRequestsError` - `431` - `RequestHeaderFieldsTooLargeError` - `500` - `InternalServerError` - `501` - `NotImplementedError` - `502` - `BadGatewayError` - `503` - `ServiceUnavailableError` - `504` - `GatewayTimeoutError` - `505` - `HttpVersionNotSupportedError` - `506` - `VariantAlsoNegotiatesError` - `507` - `InsufficientStorageError` - `509` - `BandwidthLimitExceededError` - `510` - `NotExtendedError` - `511` - `NetworkAuthenticationRequiredError` Restify will also emit the following events: ### NotFound When a client request is sent for a URL that does not exist, restify will emit this event. Note that restify checks for listeners on this event, and if there are none, responds with a default 404 handler. ### MethodNotAllowed When a client request is sent for a URL that exists, but not for the requested HTTP verb, restify will emit this event. Note that restify checks for listeners on this event, and if there are none, responds with a default 405 handler. ### VersionNotAllowed When a client request is sent for a route that exists, but does not match the version(s) on those routes, restify will emit this event. Note that restify checks for listeners on this event, and if there are none, responds with a default 400 handler. ### UnsupportedMediaType When a client request is sent for a route that exist, but has a `content-type` mismatch, restify will emit this event. Note that restify checks for listeners on this event, and if there are none, responds with a default 415 handler. ## Types ### Server~methodOpts Server method opts Type: ([String][25] \| [Regexp][46] \| [Object][24]) **Properties** - `name` **[String][25]** a name for the route - `path` **[String][25]** can be any String accepted by [find-my-way][47] **Examples** ```javascript // a static route server.get('/foo', function(req, res, next) {}); // a parameterized route server.get('/foo/:bar', function(req, res, next) {}); // a regular expression server.get('/example/:file(^\\d+).png', function(req, res, next) {}); // an options object server.get({ path: '/foo', }, function(req, res, next) {}); ``` [1]: #createserver [2]: #server [3]: #listen [4]: #close [5]: #get [6]: #head [7]: #post [8]: #put [9]: #patch [10]: #del [11]: #opts [12]: #pre [13]: #use [14]: #param [15]: #rm [16]: #address [17]: #inflightrequests [18]: #debuginfo [19]: #tostring [20]: #events [21]: #errors [22]: #types [23]: #servermethodopts [24]: https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/Object [25]: https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/String [26]: https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/Boolean [27]: https://github.com/trentm/node-bunyan [28]: https://nodejs.org/api/buffer.html [29]: https://github.com/indutny/node-spdy [30]: https://nodejs.org/api/http2.html [31]: http://nodejs.org/api/https.html#https_https [32]: #server [33]: http://nodejs.org/docs/latest/api/net.html#net_server_listen_path_callback [34]: https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/Number [35]: https://developer.mozilla.org/docs/Web/JavaScript/Reference/Statements/function [36]: https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/TypeError [37]: https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/undefined [38]: http://nodejs.org/docs/latest/api/net.html#net_event_close [39]: #servermethodopts [40]: https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/Array [41]: http://expressjs.com/guide.html#route-param%20pre-conditions [42]: http://nodejs.org/docs/latest/api/net.html#net_server_address [43]: http://nodejs.org/docs/latest/api/http.html#http_class_http_server [44]: https://nodejs.org/api/domain.html [45]: https://github.com/restify/errors [46]: https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/RegExp [47]: https://github.com/delvedor/find-my-way