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 |