Add the `Blueprint API Configuration` comments to `Routes`

[derekbasch]

The comments in "Blueprint API Configuration" (config/blueprints.js) contain some very useful and well written information.

There are superior details regarding production usage of blueprints and the differences between the blueprint types.

It also helped me to understand how sails can be configured to offer a "clean" REST API (sans fixed resource names like create).

Reference: http://stackoverflow.com/questions/256349/what-are-the-best-common-restful-url-verbs-and-actions#comment973673_256374

I took the liberty of adding some markdown to the comments:

Blueprint API Configuration

NOTE: A lot of the configuration options below affect so-called "CRUD methods", or your controllers' find, create, update, and destroy actions. It's important to realize that, even if you haven't defined these yourself, as long as a model exists with the same name as the controller, Sails will respond with built-in CRUD logic in the form of a JSON API, including support for sort, pagination, and filtering.

Action Blueprints

Action blueprints speed up the backend development workflow by eliminating the need to manually bind routes. When enabled, GET, POST, PUT, and DELETE routes will be generated for every one of a controller's actions.

If an index action exists, additional naked routes will be created for it. Finally, all actions blueprints support an optional path parameter, id, for convenience.

For example, assume we have an EmailController with actions send and index. With actions enabled, the following blueprint routes would be bound at runtime:

EmailController.index ::::::::::::::::::::::::::::::::::::::::::::::::::::::: GET /email/:id? GET /email/index/:id? POST /email/:id? POST /email/index/:id? PUT /email/:id? PUT /email/index/:id? DELETE /email/:id? DELETE /email/index/:id?

EmailController.send ::::::::::::::::::::::::::::::::::::::::::::::::::::::: GET /email/send/:id? POST /email/send/:id? PUT /email/send/:id? DELETE /email/send/:id?

actions are enabled by default, and can be OK for production-- however, if you'd like to continue to use controller/action autorouting in a production deployment, you must take great care not to inadvertently expose unsafe/unintentional controller logic to GET requests.

RESTful Blueprints

REST blueprints are the automatically generated routes Sails uses to expose a conventional REST API on top of a controller's find, create, update, and destroy actions.

For example, a BoatController with rest enabled generates the following routes: ::::::::::::::::::::::::::::::::::::::::::::::::::::::: GET /boat/:id? -> BoatController.find POST /boat -> BoatController.create PUT /boat/:id -> BoatController.update DELETE /boat/:id -> BoatController.destroy

rest blueprint routes are enabled by default, and are suitable for use in a production scenario, as long you take standard security precautions (combine w/ policies, etc.)

Shortcut Blueprints

Shortcut blueprints are simple helpers to provide access to a controller's CRUD methods from your browser's URL bar. When enabled, GET, POST, PUT, and DELETE routes will be generated for the controller's'find,create,update, anddestroy` actions.

shortcuts are enabled by default, but should be disabled in production.

An escaped version:

# Blueprint API Configuration 

_NOTE:
A lot of the configuration options below affect so-called "CRUD methods", or your controllers' `find`, `create`, `update`, and `destroy` actions. It's important to realize that, even if you haven't defined these yourself, as long as a model exists with the same name as the controller, Sails will respond with built-in CRUD logic in the form of a JSON API, including support for sort, pagination, and filtering._

## Action Blueprints

  Action blueprints speed up the backend development workflow by eliminating the need
  to manually bind routes. When enabled, GET, POST, PUT, and DELETE routes will be
  generated for every one of a controller's actions.

  If an \`index\` action exists, additional naked routes will be created for it.
  Finally, all \`actions\` blueprints support an optional path parameter, \`id\`, for convenience.

  For example, assume we have an EmailController with actions \`send\` and \`index\`.
  With \`actions\` enabled, the following blueprint routes would be bound at runtime:

  \`EmailController.index\`
  :::::::::::::::::::::::::::::::::::::::::::::::::::::::
  \`GET     /email/:id?\`        \`GET    /email/index/:id?\`
  \`POST    /email/:id?\`        \`POST   /email/index/:id?\`
  \`PUT     /email/:id?\`        \`PUT    /email/index/:id?\`
  \`DELETE  /email/:id?\`        \`DELETE /email/index/:id?\`

  \`EmailController.send\`
  :::::::::::::::::::::::::::::::::::::::::::::::::::::::
  \`GET     /email/send/:id?\`
  \`POST    /email/send/:id?\`
  \`PUT     /email/send/:id?\`
  \`DELETE  /email/send/:id?\`

  \`actions\` are enabled by default, and can be OK for production-- however,
  if you'd like to continue to use controller/action autorouting in a production deployment,
  you must take great care not to inadvertently expose unsafe/unintentional controller logic
  to GET requests.

## RESTful Blueprints

  REST blueprints are the automatically generated routes Sails uses to expose
  a conventional REST API on top of a controller's \`find\`, \`create\`, \`update\`, and \`destroy\`
  actions.

  For example, a BoatController with \`rest\` enabled generates the following routes:
  :::::::::::::::::::::::::::::::::::::::::::::::::::::::
  \`GET      /boat/:id?      -> BoatController.find\`
  \`POST     /boat           -> BoatController.create\`
  \`PUT      /boat/:id       -> BoatController.update\`
  \`DELETE   /boat/:id       -> BoatController.destroy\`

  \`rest\` blueprint routes are enabled by default, and are suitable for use
  in a production scenario, as long you take standard security precautions
  (combine w/ policies, etc.)
  rest: true,

## Shortcut Blueprints

  Shortcut blueprints are simple helpers to provide access to a controller's CRUD methods
  from your browser's URL bar.  When enabled, GET, POST, PUT, and DELETE routes will be generated
  for the controller's'find\`, \`create\`, \`update\`, and \`destroy\` actions.

  \`shortcuts\` are enabled by default, but should be disabled in production.

[derekbasch]

I noticed that some of this information is shown in the Configuration section of the documentation.

http://sailsjs.org/#!documentation/config.routes

[uncletammy]

The current documentation for v.10 lives at http://beta.sailsjs.org . It's a work in progress. If you see something that is missing, please submit a pull request to the sails-docs repo. All of the documentation on the website comes from sails-docs.

Since this issue isn’t really relevant to sails core, I'm going to close it. Feel free to send me everything you've got concerning documentation and beta.sailsjs.org in their respective repos.

Furthermore, https://github.com/balderdashy/sails/issues/1864 looks like a perfect candidate for an "Overwriting Blueprints" user guide. You can read more about them at https://github.com/balderdashy/sails-docs/blob/master/userguides/userguides.md . We would love to see what you come up with!

[derekbasch]

Thanks for the quick reply @uncletammy .

The beta docs look fantastic (compared to 0.9.x). I would really suggest putting more prominent links to the beta docs. I have been using beta for a month without knowing the docs existed :/ . Perhaps there are links somewhere and I had missed them.

I will devote a few hours to create a PR with improved Blueprint API Configuration documentation for v0.9.x.

I will also make a PR for v0.10.x. Overwriting Blueprints (ala #1864).

Glad to contribute back what I can.