Blueprint routes from sailsjs.com

Original Source

 

Blueprint routes

When you run sails lift with blueprints enabled, the framework inspects your models and configuration in order to bind certain routes automatically. These implicit blueprint routes (sometimes called "shadow routes", or even just "shadows") allow your app to respond to certain requests without you having to bind those routes manually in your config/routes.js file. When enabled, the blueprint routes point to their corresponding blueprint actions (see "Action routes" below), any of which can be overridden with custom code.

There are four types of blueprint routes in Sails:

RESTful blueprint routes

#

REST blueprints are the automatically generated routes Sails uses to expose a conventional REST API for a model, including find, create, update, and destroy actions. The path for RESTful routes is always /:modelIdentity or /:modelIdentity/:id. These routes use the HTTP "verb" to determine the action to take.

For example, with rest enabled, having a Boat model in your app generates the following routes:

• GET /boat -> find boats matching criteria provided on the query string, using the find blueprint.
• GET /boat/:id -> find a single boat with the given unique ID (i.e. primary key) value, using the findOne blueprint.
• POST /boat -> create a new boat with the attributes provided in the request body, using the create blueprint.
• PATCH /boat/:id -> update the boat with the given unique ID with the attributes provided in the request body, using the update blueprint.
• DELETE /boat/:id -> destroy the boat with the given unique ID, using the destroy blueprint.

If the Boat model has a “to-many” relationship with a Driver model through an attribute called drivers, then the following additional routes would be available:

• GET /boat/:id/drivers -> Finds the drivers' records associated to the boat record with the ID given as :id using the populate blueprint.
• PUT /boat/:id/drivers/:fk -> add the driver with the unique ID equal to the :fk value to the drivers collection of the boat with the ID given as :id, using the add blueprint.
• DELETE /boat/:id/drivers/:fk -> remove the driver with the unique ID equal to the :fk value to the drivers collection of the boat with the ID given as :id, using the remove blueprint
• PUT /boat/:id/drivers -> replace the entire drivers collection with the drivers whose unique IDs are contained in an array provided as the body of the request, using the replace blueprint.

Depending on the style of app you generated, rest blueprint routes may be enabled by default, and could be suitable for use in a production scenario, as long as they are protected by policies to avoid unauthorized access. If you choose the "Web app" template, rest blueprint routes will not be enabled by default.

Be forewarned: Most web apps, microservices, and even REST APIs eventually need custom features that aren't really as simple as "create", "update", or "destroy". If/when the time comes, don't be afraid to write your own custom actions. Custom actions and routes can, and in many cases should, still be organized as a RESTful API, and they can be mixed and matched with blueprints when necessary. Best of all, thanks to the introduction of async/await in Node.js, writing custom actions no longer requires the use of callbacks.

Notes#

• If CSRF protection is enabled, you'll need to provide or disable a CSRF token for POST/PUT/DELETE actions, otherwise you will get a 403 Forbidden response.
• If your app contains a controller whose name matches that of your model, then you can override the default actions pointed to by the RESTful routes by providing your own controller actions. For example, if you have an api/controllers/BoatController.js controller file containing a custom find action, then the GET /boat route will point at that action.
• Also, as usual, the same logic applies whether you're using controllers or standalone actions. (As far as Sails is concerned, once an app has been loaded into memory and normalized in sails lift, all of its actions look the same no matter where they came from.)
• If your app contains a route in config/routes.js that matches one of the above RESTful routes, it will be used instead of the default route.

Shortcut blueprint routes

#

Shortcut routes are a simple (development-mode only) hack that provides access to your models from your browser's URL bar.

The shortcut routes are as follows:

 

The rest is omitted...