Edit Page

Custom responses

Overview

#

Sails apps come bundled with several pre-configured responses that can be called from action code. These default responses can handle situations like “resource not found” (the notFound response) and “internal server error” (the serverError response). If your app needs to modify the way that the default responses work, or create new responses altogether, you can do so by adding files to the api/responses folder.

Note: api/responses is not generated by default in new Sails apps, so you’ll have to add it yourself if you want to add / customize responses.

Using responses

#

As a quick example, consider the following action:

getProfile: function(req, res) {

  // Look up the currently logged-in user's record from the database.
  User.findOne({ id: req.session.userId }).exec(function(err, user) {
    if (err) {
      res.status(500);
      return res.view('500', {data: err});
    }

    return res.json(user);
  });
}

This code handles a database error by sending a 500 error status and sending the error data to a view to be displayed. However, this code has several drawbacks, primarily:

Now, consider this replacement:

getProfile: function(req, res) {

  // Look up the currently logged-in user's record from the database.
  User.findOne({ id: req.session.userId }).exec(function(err, user) {
    if (err) { return res.serverError(err); }
    return res.json(user);
  });
}

This approach has many advantages:

Response methods and files

#

Any .js file saved in the api/responses/ folder can be executed by calling res.thatFileName(). For example, api/responses/insufficientFunds.js can be executed with a call to res.insufficientFunds().

Accessing req, res, and sails
#

The request and response objects are available inside of a custom response as this.req and this.res. This allows the actual response function to take arbitrary parameters. For example:

return res.insufficientFunds(err, { happenedDuring: 'signup' });

And the implementation of the custom response might look something like this:

module.exports = function insufficientFunds(err, extraInfo){

  var req = this.req;
  var res = this.res;
  var sails = req._sails;

  var newError = new Error('Insufficient funds');
  newError.raw = err;
  _.extend(newError, extraInfo);

  sails.log.verbose('Sent "Insufficient funds" response.');

  return res.badRequest(newError);

}

Built-in responses

#

All Sails apps have several pre-configured responses like res.serverError() and res.notFound() that can be used even if they don’t have corresponding files in api/responses/.

Any of the default responses may be overridden by adding a file with the same name to api/responses/ in your app (e.g. api/responses/serverError.js).

You can use the Sails command-line tool as a shortcut for doing this.

For example:

sails generate response serverError

Is something missing?

If you notice something we've missed or could be improved on, please follow this link and submit a pull request to the sails repo. Once we merge it, the changes will be reflected on the website the next time it is deployed.

Concepts