2017-10-13 01:23:18 +02:00
---
title: Server API
permalink: /docs/server-api/
---
<!-- Generated by documentation.js. Update this documentation by updating the source code. -->
### Table of Contents
2018-04-20 11:44:05 -07:00
- [createServer ](#createserver )
- [Server ](#server )
- [listen ](#listen )
- [close ](#close )
- [get ](#get )
- [head ](#head )
- [post ](#post )
- [put ](#put )
- [patch ](#patch )
- [del ](#del )
- [opts ](#opts )
- [pre ](#pre )
- [use ](#use )
- [param ](#param )
- [rm ](#rm )
- [address ](#address )
- [inflightRequests ](#inflightrequests )
- [debugInfo ](#debuginfo )
- [toString ](#tostring )
- [Events ](#events )
- [Errors ](#errors )
- [Types ](#types )
- [Server~methodOpts ](#servermethodopts )
2017-10-13 01:23:18 +02:00
## createServer
A restify server object is the main interface through which you will register
routes and handlers for incoming requests.
**Parameters **
2018-04-20 11:44:05 -07:00
- `options` * * [Object ](https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/Object )?** an options object
- `options.name` * * [String ](https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/String )** Name of the server. (optional, default `"restify"` )
- `options.dtrace` * * [Boolean ](https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/Boolean )** enable DTrace support (optional, default `false` )
2017-10-13 01:23:18 +02:00
- `options.router` **Router ** Router (optional, default `newRouter(opts)` )
2018-04-20 11:44:05 -07:00
- `options.log` * * [Object ](https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/Object )** [bunyan ](https://github.com/trentm/node-bunyan ) instance. (optional, default `bunyan.createLogger(options.name||"restify")` )
- `options.url` * * [String ](https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/String )?** Once listen() is called, this will be filled
2017-10-13 01:23:18 +02:00
in with where the server is running.
2018-04-20 11:44:05 -07:00
- `options.certificate` * * ([String ](https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/String ) \| [Buffer ](https://nodejs.org/api/buffer.html ))?** If you want to create an HTTPS
2017-10-13 01:23:18 +02:00
server, pass in a PEM-encoded certificate and key.
2018-04-20 11:44:05 -07:00
- `options.key` * * ([String ](https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/String ) \| [Buffer ](https://nodejs.org/api/buffer.html ))?** If you want to create an HTTPS server,
2017-10-13 01:23:18 +02:00
pass in a PEM-encoded certificate and key.
2018-04-20 11:44:05 -07:00
- `options.formatters` * * [Object ](https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/Object )?** Custom response formatters for
2017-10-13 01:23:18 +02:00
`res.send()` .
2018-04-20 11:44:05 -07:00
- `options.handleUncaughtExceptions` * * [Boolean ](https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/Boolean )** When true restify
2017-10-13 01:23:18 +02:00
will use a domain to catch and respond to any uncaught
exceptions that occur in it's handler stack.
2018-04-20 11:44:05 -07:00
[bunyan ](https://github.com/trentm/node-bunyan ) instance.
2018-03-20 11:10:28 -07:00
response header, default is `restify` . Pass empty string to unset the header.
Comes with significant negative performance impact. (optional, default `false` )
2018-04-20 11:44:05 -07:00
- `options.spdy` * * [Object ](https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/Object )?** Any options accepted by
[node-spdy ](https://github.com/indutny/node-spdy ).
- `options.http2` * * [Object ](https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/Object )?** Any options accepted by
[http2.createSecureServer ](https://nodejs.org/api/http2.html ).
- `options.handleUpgrades` * * [Boolean ](https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/Boolean )** Hook the `upgrade` event
2017-10-13 01:23:18 +02:00
from the node HTTP server, pushing `Connection: Upgrade` requests through the
regular request handling chain. (optional, default `false` )
2018-06-10 15:44:57 -07:00
- `options.onceNext` * * [Boolean ](https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/Boolean )** Prevents calling next multiple
times (optional, default `false` )
- `options.strictNext` * * [Boolean ](https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/Boolean )** Throws error when next() is
called more than once, enabled onceNext option (optional, default `false` )
2018-04-20 11:44:05 -07:00
- `options.httpsServerOptions` * * [Object ](https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/Object )?** Any options accepted by
[node-https Server ](http://nodejs.org/api/https.html#https_https ).
2017-10-13 01:23:18 +02:00
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.
2018-06-10 15:44:57 -07:00
- `options.noWriteContinue` * * [Boolean ](https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/Boolean )** prevents
`res.writeContinue()` in `server.on('checkContinue')` when proxing (optional, default `false` )
2018-04-20 11:44:05 -07:00
- `options.ignoreTrailingSlash` * * [Boolean ](https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/Boolean )** ignore trailing slash
2018-03-26 16:45:23 -07:00
on paths (optional, default `false` )
2019-01-09 16:38:09 -08:00
- `options.strictFormatters` * * [Boolean ](https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/Boolean )** 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` )
2017-10-13 01:23:18 +02:00
**Examples **
``` javascript
var restify = require ( 'restify' ) ;
var server = restify . createServer ( ) ;
2017-12-18 15:21:13 -08:00
server . listen ( 8080 , function ( ) {
console . log ( 'ready on %s' , server . url ) ;
2017-10-13 01:23:18 +02:00
} ) ;
```
2018-04-20 11:44:05 -07:00
Returns * * [Server ](#server )** server
2017-10-13 01:23:18 +02:00
## Server
Creates a new Server.
**Parameters **
2018-04-20 11:44:05 -07:00
- `options` * * [Object ](https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/Object )** an options object
- `options.name` * * [String ](https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/String )** Name of the server.
- `options.dtrace` * * [Boolean ](https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/Boolean )** enable DTrace support (optional, default `false` )
2017-10-13 01:23:18 +02:00
- `options.router` **Router ** Router
2018-04-20 11:44:05 -07:00
- `options.log` * * [Object ](https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/Object )** [bunyan ](https://github.com/trentm/node-bunyan )
2017-10-13 01:23:18 +02:00
instance.
2018-04-20 11:44:05 -07:00
- `options.url` * * [String ](https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/String )?** Once listen() is called, this will be filled
2017-10-13 01:23:18 +02:00
in with where the server is running.
2018-04-20 11:44:05 -07:00
- `options.certificate` * * ([String ](https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/String ) \| [Buffer ](https://nodejs.org/api/buffer.html ))?** If you want to create an HTTPS
2017-10-13 01:23:18 +02:00
server, pass in a PEM-encoded certificate and key.
2018-04-20 11:44:05 -07:00
- `options.key` * * ([String ](https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/String ) \| [Buffer ](https://nodejs.org/api/buffer.html ))?** If you want to create an HTTPS server,
2017-10-13 01:23:18 +02:00
pass in a PEM-encoded certificate and key.
2018-04-20 11:44:05 -07:00
- `options.formatters` * * [Object ](https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/Object )?** Custom response formatters for
2017-10-13 01:23:18 +02:00
`res.send()` .
2018-04-20 11:44:05 -07:00
- `options.handleUncaughtExceptions` * * [Boolean ](https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/Boolean )** When true restify
2017-10-13 01:23:18 +02:00
will use a domain to catch and respond to any uncaught
exceptions that occur in it's handler stack.
2018-03-20 11:10:28 -07:00
Comes with significant negative performance impact.
2018-04-20 11:44:05 -07:00
[bunyan ](https://github.com/trentm/node-bunyan ) instance.
2017-10-13 01:23:18 +02:00
response header, default is `restify` . Pass empty string to unset the header. (optional, default `false` )
2018-04-20 11:44:05 -07:00
- `options.spdy` * * [Object ](https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/Object )?** Any options accepted by
[node-spdy ](https://github.com/indutny/node-spdy ).
- `options.http2` * * [Object ](https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/Object )?** Any options accepted by
[http2.createSecureServer ](https://nodejs.org/api/http2.html ).
- `options.handleUpgrades` * * [Boolean ](https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/Boolean )** Hook the `upgrade` event
2017-10-13 01:23:18 +02:00
from the node HTTP server, pushing `Connection: Upgrade` requests through the
regular request handling chain. (optional, default `false` )
2018-04-20 11:44:05 -07:00
- `options.onceNext` * * [Boolean ](https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/Boolean )** Prevents calling next multiple
2018-03-20 11:10:28 -07:00
times (optional, default `false` )
2018-04-20 11:44:05 -07:00
- `options.strictNext` * * [Boolean ](https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/Boolean )** Throws error when next() is
2018-03-20 11:10:28 -07:00
called more than once, enabled onceNext option (optional, default `false` )
2018-04-20 11:44:05 -07:00
- `options.httpsServerOptions` * * [Object ](https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/Object )?** Any options accepted by
[node-https Server ](http://nodejs.org/api/https.html#https_https ).
2017-10-13 01:23:18 +02:00
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.
2018-04-20 11:44:05 -07:00
- `options.noWriteContinue` * * [Boolean ](https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/Boolean )** prevents
2018-03-20 11:10:28 -07:00
`res.writeContinue()` in `server.on('checkContinue')` when proxing (optional, default `false` )
2018-04-20 11:44:05 -07:00
- `options.ignoreTrailingSlash` * * [Boolean ](https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/Boolean )** ignore trailing slash
2018-03-26 16:45:23 -07:00
on paths (optional, default `false` )
2019-01-09 16:38:09 -08:00
- `options.strictFormatters` * * [Boolean ](https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/Boolean )** 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` )
2017-10-13 01:23:18 +02:00
**Examples **
``` javascript
var restify = require ( 'restify' ) ;
2018-03-17 16:10:55 -07:00
var server = restify . createServer ( ) ;
2017-10-13 01:23:18 +02:00
2017-12-18 15:21:13 -08:00
server . listen ( 8080 , function ( ) {
console . log ( 'ready on %s' , server . url ) ;
2017-10-13 01:23:18 +02:00
} ) ;
```
### listen
Gets the server up and listening.
Wraps node's
2018-04-20 11:44:05 -07:00
[listen() ](http://nodejs.org/docs/latest/api/net.html#net_server_listen_path_callback ).
2017-10-13 01:23:18 +02:00
**Parameters **
2018-04-20 11:44:05 -07:00
- `port` * * [Number ](https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/Number )** Port
- `host` * * [Number ](https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/Number )?** Host
- `callback` * * [Function ](https://developer.mozilla.org/docs/Web/JavaScript/Reference/Statements/function )?** optionally get notified when listening.
2017-10-13 01:23:18 +02:00
**Examples **
_ You can call like: _
``` javascript
server . listen ( 80 )
server . listen ( 80 , '127.0.0.1' )
server . listen ( '/tmp/server.sock' )
```
2018-04-20 11:44:05 -07:00
- Throws * * [TypeError ](https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/TypeError )**
2017-10-13 01:23:18 +02:00
2018-04-20 11:44:05 -07:00
Returns * * [undefined ](https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/undefined )** no return value
2017-10-13 01:23:18 +02:00
### close
Shuts down this server, and invokes callback (optionally) when done.
Wraps node's
2018-04-20 11:44:05 -07:00
[close() ](http://nodejs.org/docs/latest/api/net.html#net_event_close ).
2017-10-13 01:23:18 +02:00
**Parameters **
2018-04-20 11:44:05 -07:00
- `callback` * * [Function ](https://developer.mozilla.org/docs/Web/JavaScript/Reference/Statements/function )?** callback to invoke when done
2017-10-13 01:23:18 +02:00
2018-04-20 11:44:05 -07:00
Returns * * [undefined ](https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/undefined )** no return value
2017-10-13 01:23:18 +02:00
### get
Mounts a chain on the given path against this HTTP verb
**Parameters **
2018-04-20 11:44:05 -07:00
- `opts` * * [Server~methodOpts ](#servermethodopts )** if string, the URL to handle.
2017-10-13 01:23:18 +02:00
if options, the URL to handle, at minimum.
2017-10-19 19:57:14 +02:00
**Examples **
``` javascript
server . get ( '/' , function ( req , res , next ) {
res . send ( { hello : 'world' } ) ;
next ( ) ;
} ) ;
```
2017-10-13 01:23:18 +02:00
Returns **Route ** the newly created route.
### head
Mounts a chain on the given path against this HTTP verb
**Parameters **
2018-04-20 11:44:05 -07:00
- `opts` * * [Server~methodOpts ](#servermethodopts )** if string, the URL to handle.
2017-10-13 01:23:18 +02:00
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 **
2018-04-20 11:44:05 -07:00
- `post` * * [Server~methodOpts ](#servermethodopts )** if string, the URL to handle.
2017-10-13 01:23:18 +02:00
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 **
2018-04-20 11:44:05 -07:00
- `put` * * [Server~methodOpts ](#servermethodopts )** if string, the URL to handle.
2017-10-13 01:23:18 +02:00
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 **
2018-04-20 11:44:05 -07:00
- `patch` * * [Server~methodOpts ](#servermethodopts )** if string, the URL to handle.
2017-10-13 01:23:18 +02:00
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 **
2018-04-20 11:44:05 -07:00
- `opts` * * [Server~methodOpts ](#servermethodopts )** if string, the URL to handle.
2017-10-13 01:23:18 +02:00
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 **
2018-04-20 11:44:05 -07:00
- `opts` * * [Server~methodOpts ](#servermethodopts )** if string, the URL to handle.
2017-10-13 01:23:18 +02:00
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 **
2018-04-20 11:44:05 -07:00
- `handler` * * ...([Function ](https://developer.mozilla.org/docs/Web/JavaScript/Reference/Statements/function ) \| [Array ](https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/Array ))** Allows you to add handlers that
2017-10-24 22:22:30 +02:00
run for all routes. _ before _ routing occurs.
2017-10-13 01:23:18 +02:00
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 ( ) ) ;
```
2018-04-20 11:44:05 -07:00
Returns * * [Object ](https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/Object )** returns self
2017-10-13 01:23:18 +02:00
### 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 **
2018-04-20 11:44:05 -07:00
- `handler` * * ...([Function ](https://developer.mozilla.org/docs/Web/JavaScript/Reference/Statements/function ) \| [Array ](https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/Array ))** A variable number of handler functions- and/or a
2017-10-13 01:23:18 +02:00
variable number of nested arrays of handler functions
2018-04-20 11:44:05 -07:00
Returns * * [Object ](https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/Object )** returns self
2017-10-13 01:23:18 +02:00
### param
2018-04-20 11:44:05 -07:00
- **See: <http://expressjs.com/guide.html#route-param%20pre-conditions> **
2017-10-24 22:22:30 +02:00
2017-10-13 01:23:18 +02:00
Minimal port of the functionality offered by Express.js Route Param
Pre-conditions
2017-10-24 22:22:30 +02:00
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()
});
2017-10-13 01:23:18 +02:00
**Parameters **
2018-04-20 11:44:05 -07:00
- `name` * * [String ](https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/String )** The name of the URL param to respond to
- `fn` * * [Function ](https://developer.mozilla.org/docs/Web/JavaScript/Reference/Statements/function )** The middleware function to execute
2017-10-13 01:23:18 +02:00
2018-04-20 11:44:05 -07:00
Returns * * [Object ](https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/Object )** returns self
2017-10-13 01:23:18 +02:00
### rm
Removes a route from the server.
You pass in the route 'blob' you got from a mount call.
**Parameters **
2018-04-20 11:44:05 -07:00
- `routeName` * * [String ](https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/String )** the route name.
2017-10-13 01:23:18 +02:00
2018-04-20 11:44:05 -07:00
- Throws * * [TypeError ](https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/TypeError )** on bad input.
2017-10-13 01:23:18 +02:00
2018-04-20 11:44:05 -07:00
Returns * * [Boolean ](https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/Boolean )** true if route was removed, false if not.
2017-10-13 01:23:18 +02:00
### address
Returns the server address.
Wraps node's
2018-04-20 11:44:05 -07:00
[address() ](http://nodejs.org/docs/latest/api/net.html#net_server_address ).
2017-10-13 01:23:18 +02:00
2017-10-19 19:57:14 +02:00
**Examples **
``` javascript
server . address ( )
```
_ Output: _
``` javascript
{ address : '::' , family : 'IPv6' , port : 8080 }
```
2018-04-20 11:44:05 -07:00
Returns * * [Object ](https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/Object )** Address of server
2017-10-13 01:23:18 +02:00
### inflightRequests
Returns the number of inflight requests currently being handled by the server
2018-04-20 11:44:05 -07:00
Returns * * [number ](https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/Number )** number of inflight requests
2017-10-13 01:23:18 +02:00
### debugInfo
Return debug information about the server.
2017-10-19 19:57:14 +02:00
**Examples **
``` javascript
server . getDebugInfo ( )
```
_ Output: _
``` javascript
2017-10-24 22:22:30 +02:00
{
routes : [
{
2017-10-19 19:57:14 +02:00
name : 'get' ,
method : 'get' ,
input : '/' ,
compiledRegex : /^[\/]*$/ ,
compiledUrlParams : null ,
handlers : [ Array ]
}
] ,
2017-10-24 22:22:30 +02:00
server : {
formatters : {
2017-10-19 19:57:14 +02:00
'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 : [ ]
}
}
```
2018-04-20 11:44:05 -07:00
Returns * * [Object ](https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/Object )** debug info
2017-10-13 01:23:18 +02:00
### toString
toString() the server for easy reading/output.
2017-10-19 19:57:14 +02:00
**Examples **
``` javascript
server . toString ( )
```
_ Output: _
``` javascript
2017-10-24 22:22:30 +02:00
Accepts : application / json , text / plain , application / octet - stream ,
2017-10-19 19:57:14 +02:00
application / javascript
Name : restify
Pre : [ ]
Router : RestifyRouter :
DELETE : [ ]
GET : [ get ]
HEAD : [ ]
OPTIONS : [ ]
PATCH : [ ]
POST : [ ]
PUT : [ ]
2017-10-24 22:22:30 +02:00
Routes :
2017-10-19 19:57:14 +02:00
get : [ parseQueryString , _jsonp , function ]
Secure : false
Url : http : //[::]:8080
Version :
```
2018-04-20 11:44:05 -07:00
Returns * * [String ](https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/String )** stringified server
2017-10-13 01:23:18 +02:00
## Events
In additional to emitting all the events from node's
2018-04-20 11:44:05 -07:00
[http.Server ](http://nodejs.org/docs/latest/api/http.html#http_class_http_server ),
2017-10-13 01:23:18 +02:00
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 ) { }
```
2017-10-19 19:57:14 +02:00
- `req` - the request object
- `res` - the response object
- `route` - the route object that serviced the request
- `error` - the error passed to `next()` , if applicable
2017-10-13 01:23:18 +02:00
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 ) { }
```
2017-10-19 19:57:14 +02:00
- `req` - the request object
- `res` - the response object
2017-10-13 01:23:18 +02:00
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 ) { }
```
2017-10-19 19:57:14 +02:00
- `req` - the request object
- `res` - the response object
- `route` - the route object that serviced the request
2017-10-13 01:23:18 +02:00
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` ,
2018-04-20 11:44:05 -07:00
restify will leverage [domains ](https://nodejs.org/api/domain.html ) to handle
2017-10-13 01:23:18 +02:00
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 ) { }
```
2017-10-19 19:57:14 +02:00
- `req` - the request object
- `res` - the response object
- `route` - the route object that serviced the request
- `error` - the error passed to `next()` , if applicable
2017-10-13 01:23:18 +02:00
### 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 ) { }
```
2017-10-19 19:57:14 +02:00
- `req` - the request object
- `res` - the response object
- `err` - the error object
- `callback` - a callback function to invoke
2017-10-13 01:23:18 +02:00
When using this feature in conjunction with
2018-04-20 11:44:05 -07:00
[restify-errors ](https://github.com/restify/errors ), restify will emit events
2017-10-13 01:23:18 +02:00
for all of the basic http errors:
2017-10-19 19:57:14 +02:00
- `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`
2017-10-13 01:23:18 +02:00
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
2018-04-20 11:44:05 -07:00
Type: ([String ](https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/String ) \| [Regexp ](https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/RegExp ) \| [Object ](https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/Object ))
2017-10-13 01:23:18 +02:00
**Properties **
2018-04-20 11:44:05 -07:00
- `name` * * [String ](https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/String )** a name for the route
- `path` * * [String ](https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/String )** can be any String accepted by
[find-my-way ](https://github.com/delvedor/find-my-way )
2017-10-13 01:23:18 +02:00
**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
2018-03-20 11:10:28 -07:00
server . get ( '/example/:file(^\\d+).png' , function ( req , res , next ) { } ) ;
2017-10-13 01:23:18 +02:00
// an options object
server . get ( {
path : '/foo' ,
} , function ( req , res , next ) { } ) ;
```
