What do you think of:

Sails controller roadmap.js

// UserController.js

module.exports = {
  
  // The new way
  test1: function() {
    
    // contexual access to params
    // (this is probably the most valuable piece-- normalizes stuff between req.params, req.query, req.body, and socket.io)
    this.name;
    
    // An object containing all params
    // (that means a sane merge of the path params, the query string, and even the parsed HTTP body)
    this.params;
    
    // Send back an error (500)
    return new Error('Something bad happened!');
    
    // Send back a JSON response (200)
    return {
      success: true
    };
    
  },
  
  
  // Diving deeper
  test2: function (req,res) {
    
    // But Mike, what about callbacks?
    // Well, that part kind of sucks still..
    // (not a lot we can do here, since javscript kills scope)
    
    // Shortcut sends a 200
    // string or JSON can be sent back
    res.ok === res.send;
    res.ok();
    res.ok('optional string');
    res.ok({message: 'or json'});
    res.ok({message: 'or json'});
    
    // Shortcut sends a 404
    res.notFound() === res.send(404);
    res.notFound('optional message');
    res.notFound({message: 'or some json'});
    
    // Shortcut sends a 500
    res.send(500) === res.send(new Error) === res.error();
    res.error('optional message');
    res.error({message: 'or some json'});
    
    
    // Example
    User.find(this.id).done(function (err, user) {
      if (err) {
        return res.error(err);
      }
      else if (!user) {
        return res.notFound();
      }
      else {
        return res.ok();
      }
    });
    
    // But in the future, we might be able to use deferred objects
    // it's just that if you're doing anything with any modules that aren't a part of Sails, they won't necessarily work like this
    // But for posterity: e.g.
    return User.find(7);
    
    // Sexy right?  Maybe for this summer....!  That's a tall order.
    
  },
  
  function test3 (req,res) {
    
    // Anyways, what about realtime?
  
    // Arbitrary broadcast to sockets in a room
    this.broadcast({
      something: 'a message'
    }).to('roomname');
    
    // Or leverage the model
    
    // subscribe to all changes to any dog in the Dog collection
    Dog.subscribe();
    
    // subscribe to changes to dog #3
    Dog.subscribe(3);
    
    // publish the fact that a new Dog has been created
    Dog.introduce();
    
    // publish a message to all users subscribed to the Dog collection
    Dog.publish();
    
    // publish a message to all users subscribed to Dog #5
    Dog.publish(5);
    
  }
  
  
  // But you can still get to req and res if you need them
  // The "old way"
  oldWay: function (req,res) {
    
    // Req: params, headers, other raw request data
    var bar = req.param('bar');
    
    // And req.socket if you need direct access to socket.io
    req.socket.broadcast.to('roomName').emit('enter',{
      type: 'arbitrary message',
      description: 'mustard is not nearly as delicious in my oatmeal'
    });
    
    // Direct control of HTTP/WS response
    res.send(500);
  }
}

Just thinking about this.What I said earlier applies when you build your API around resources. Thus a resource (e.g. User) can have a subresource, or a list of subresources (e.g. Books). When the user creates it makes a post to server to /api/users/:userid/books . In BooksController it is created the book and the execution continues to UsersController for updating the User (which has that book). I was thinking if it's a good (scalable) ideea to have a controller on it's own only for responding to API requests, let's call it ResponseController. thus the execution goes to BooksController (book created), then UsersController (user updated) then ResponseController which parses the req.responseObject (just a naming convention... could be named whatever...) property and ends the response with a res.json method. What do you think?