3 routing - Atlantis-Software/synapps GitHub Wiki

Routing refers to determining how an application responds to a client request to a particular endpoint, which is a URI (or path)

Route definition takes the following structure:

app.METHOD(PATH, [OPTIONS,] HANDLER);

Where:

  • app is an instance of synapps.
  • METHOD is one of the following sample methods.
  • PATH is a path on the server.
  • OPTIONS is an object that define options for this route (this is an optional argument).
  • HANDLER is the function executed when the route is matched.

This tutorial assumes that an instance of synapps named app is created and the server is running. If you are not familiar with creating an app and starting it, see the Hello world example.

The following example illustrate defining a simple route. Respond with Hello World! on root url / for any kind of request:

app.route('/', function(req) {
  req.resolve('Hello World!');
});

Respond to GET request on the root route (/), the application’s home page:

app.get('/', function(req) {
  req.resolve('Hello World!');
});

Respond to a POST request

app.post('/', function(req) {
  req.resolve('Hello World!');
});

Respond to a PUT request

app.put('/', function(req) {
  req.resolve('Hello World!');
});

Respond to a DELETE request

app.delete('/', function(req) {
  req.resolve('Hello World!');
});

Route paths

Route paths, define the endpoints at which requests can be made. Route paths are strings.

Query strings are not part of the route path.

Here are some examples of route paths.

This route path will match requests to the root route, /.

app.route('/', function(req) {
  req.resolve('root');
});

This route path will match requests to /about.

app.route('/about', function(req) {
  req.resolve('about');
});

This route path will match requests to /about/me.

app.route('/about/me', function(req) {
  req.resolve('about me');
});

Route options

Route options is an Object describing all route options like:

policy (mixed): Takes either a string referencing a pre-declared policy, or a function, or an array of them.

app.route('/user', {
    policy: 'private'
  }, function(req) {
    req.resolve('OK');
});
app.route('/user', {
    policy: function(req, cb) {
      // check if user is registered
      if (isRegistered(req)) {
        return cb();
      }
      cb(new Error('unregistered user'));
    }
  }, function(req) {
    req.resolve('OK');
});
app.route('/admin', {
    policy: [function(req, cb) {
      // check if user is registered
      if (isRegistered(req)) {
        return cb();
      }
      cb(new Error('unregistered user'));
    }, 'isadmin']
  }, function(req) {
    req.resolve('OK');
});

input (object): Each property of this object is a possible value allowed in input (req.data), they MUST include at least a type.

app.route('/get/book', {
    input: {
      bookId: {
        type: 'integer',
        required: true
      }
      lang: {
        type: 'string'
      }
    }
  }, function(req) {
    req.resolve(req.data);
});

Route parameters

Route parameters are named URL segments that are used to capture the values specified at their position in the URL. The captured values are populated in the req.data object (options can specify them in input section to overwrite 'string' default type), with the name of the route parameter specified in the path as their respective keys.

Route path: /users/:userId/books/:bookId
Request URL: http://localhost:3000/users/34/books/8989
options input: { userId: { type: 'integer' }, bookId: { type: 'integer' }
req.data: { "userId": 34, "bookId": 8989 }

To define routes with route parameters, simply specify the route parameters in the path of the route as shown below.

app.route('/users/:userId/books/:bookId', {
    input: {
      userId: {
        type: 'integer'
      },
      bookId: {
        type: 'integer'
      }
    }
  }, function(req) {
    req.resolve(req.data);
});

The name of route parameters must be made up of “word characters” ([A-Za-z0-9_]).

Route handler

route handler is single callback function that can handle a route. For example:

app.route('/', function(req) {
  req.resolve('hello from handler');
});

Req methods

The methods on the request object (req) in the following table can send a response to the client, and terminate the request-response cycle. If none of these methods are called from a route handler, the client request will be left hanging.

Method Description
resolve successfully send the response.
reject send error.
notify send a notification (socket io only)
setHeader set an http header field (http only)
debug add a debug message to the log