Primer on Sails.js Blueprints.

Sails.js comes pre-packed with quite a number of things that make life easier. Blueprints are one of them. They take the stress out of creating routes and actions in your API.

Because Blueprints do a lot of awesome things automagically, it's important to know exactly what they do, when to use them and when not to.

Whenever you create a new Sails.js application, Blueprints are turned on automatically. You can either turn them off entirely or you can turn off/override the exact aspects you do not want. We'll see how to do exactly that as we proceed.

There are three kinds of Blueprint routes that we're gonna look at.

RESTful Routes

When you create a model User.js and a corresponding controller UserController.js, Sails does a couple of things for you automatically.

1 Default Actions

It automatically applies eight actions to that model: find, findOne, create, update, destroy, populate, add and remove. The first five actions need no explanation.

populate gets foreign record(s) for a given association.

add adds a foreign record. E.g Adding a Tweet to a User.

remove does the opposite of what add does.

2 Default Routes

It applies intuitive routes to the actions above. They use the HTTP verb of a request to determine what action to take.

POST /user will create a new user.

DELETE /user/123 will destroy the user whose primary key is 123.

GET /user?age=25 will find users whose age = 25 while GET /user/123 will findOne user whose primary key is 123.

PUT /user/123 will update the user whose primary key is 123.

GET /user/123/tweet will populate the tweets of the user whose primary key is 123.

POST /user/123/tweet will add a new tweet that's associated with the user whose primary key is 123.

DELETE /user/123/tweet/1 will remove the tweet with a foreign key of 1 from the user whose primary key is 123. This action does not delete the foreign/associated record, it just removes the association.

How to override & deactivate

To deactivate RESTful routes entirely, you need to set sails.config.blueprint.rest to false (in /config/blueprints.js).

To deactivate RESTful routes for a single controller:

module.exports = {
_config: {
rest: false
}
}

To override a RESTful action for a single controller, create an action in that controller with the same name as the action you're trying to override.

To override the default Blueprint action that all controllers use, you need to create an api/blueprints folder add files to it with names matching the actions you want to override (e.g find.js, findone.js, create.js etc.) To see how the default sails Blueprint actions work, you can check out the code for each one here.

Note that the files in api/blueprints need to have lower case file names. (The default actions in the Sails.js source code has a findOne.js but your custom implementation needs to be findone.js.

Shortcut Routes

Like with RESTful Routes, Shortcut Routes are activated by default when you create a model-controller pair; /models/User.js and /controllers/UserController.js

When Shortcut Routes are activated, Sails automatically tries to detect what action/method to call in your controller by checking the url of the request.

For example, GET /user/create?name=Timi will run the same code as POST /user, even if the default blueprint action has been overridden.

Also GET /user/update/1?name=AnotherName will run the update action in the UserController and as such update the user with an ID of 1.

Shortcut routes only respond to GET requests and are useful in development for quickly testing endpoints. You might want to consider turning them off in production.

How to override & deactivate

To deactivate Shortcut Routes entirely, you need to set sails.config.blueprint.shortcuts to false (in /config/blueprints.js).

To deactivate Shortcut Routes for a single controller:

module.exports = {
_config: {
shortcuts: false
}
}

Action Routes

Unlike with RESTful routes and Shortcut routes, action routes don’t need you to create a model-controller pair. It’s activated by default when a controller is created.

When Action Routes are activated, any method/action added in your controller will have a route created for it at /controller-name/method

This means that automatically, a route would be created at /user/slap that will point to that slap method.

One drawback however, is that this route and action will respond to all HTTP Verbs; GET, POST, PATCH, PUT, DELETE. The way around this would be to use req.method to determine the request method and then wrap the action’s functionality in a condition.