RouteInterface

tries to determine the route definition location

unique identifier of the route

Parameters:

• options
• Type: Object
• name optional
• Type: String
• url
• Type: String
• summary
• Type: String

• swagger doc

• desc
• Type: String

• swagger doc

• sdkMethodName
• Type: String

• client sdk method name

Throws:

returns collection of supported request content mime types

define which content-type headers the route supports.
this method can be called multiple times to define different accepted data formats.
NOTE: this is also gonna register and manage a single validation middleware for content-type header internally
NOTE: only json/urlencoded/raw/text media types have fallback parsers defined. if you want to support any other data format, you must also provide a parsing function with it...

Parameters:

• mediaType
• Type: String

• accepted Content-Type header value as defined by RFC 7231

• options optional
• Type: Object
• limit optional
• Type: String

• data size limit

• parser optional
• Type: function

• custom data parser function - is provided with req object & must return a Promise

allows to hook up any middleware function to the request promise chain (call stack)

Parameters:

• name optional
• Type: String

• fn
• Type: function

the Response object can be returned from within route middleware which will cause promise call chain interruption of current request and prioritized response

Parameters:

• cb
• Type: function

• callback function which sets response on the express res object. The function's context is always set to the res object

route.step(function() {
    return route.buildResponse(function() {
        this.json({response: 'data'});
    }):
}).step(function() {
    //will never be called
});

catch promise stack handler invoked when an Error occurs while executing one of the route middlwares

Parameters:

• filter optional
• Type: function

• must be a constructor with .prototype property that is instanceof Error

• callback
• Type: function

route.main(function() {
  throw new TypeError('test');
}).catch(TypeError, function(err, req, res) {
  //err handler logic
});

returns route's internal middleware call stack

returns route's name. If no name has been assigned, the name is dynamically created from route's url path

Parameters:

• fn
• Type: function

route.main(() => {})

//is same as:

route.step('main', () => {})

define a content-type which should be always rejected by this route. Content types blacklisted by this method can be later whitelisted by the RouteInterface#acceptsContentType method

Parameters:

• type
• Type: String

• Content-Type header value

allows to describe route's response data format in form of Ajv validation schema object or Error instance object/constructor which implements toSwagger method.
if a string is provided it's expected to be validation schema unique indentifier registered with the Ajv instance.
Consecutive calls with response schema for HTTP 200 OK status code overwrite the previously set schema.
However, consecutive calls related to any other HTTP status code will merge the provided schema with the one previously set. This allows us to describe nuances in different failure scenarios - like a 400 response with mulitple possible apiCode values.
With conjuction of res.filter({some: 'data'}).json(), data can be filtered with defined response schema.

Parameters:

• descriptor
• Type: Object or String or function

//200 OK
route.respondsWith({
    type: 'object',
    additionalProperties: false,
    properties: {
        prop1: {type: 'string'}
    }
});

//401 Unauthorized generic failure
route.respondsWith(UnauthorizedError);

//400 Bad Request specific failure
route.respondsWith(new RequestError({
    apiCode: 'entityAlreadyExists'
}));

//example of response data filtering
route.main(function(req, res) {
    res.filter({prop1: 'included', prop2: 'filtered out'}).json();
});

alias for RouteInterface#addStep

Parameters:

• name optional
• Type: String

• fn
• Type: function

pushes specifically configured validation middleware to the route's call stack

Parameters:

• valDef
• Type: string or Object

• string => registered validator's name. Object => schema definition

• dataProp
• Type: string

• any of available properties of the req object - eg.: query|body|params|headers

route.validate({
    properties: {
        username: {type: 'string'}
    }
}, 'query');

//or

route.validate('ajv-registered-validation-schema-uid', 'body');