Skip to content

Home

sakno edited this page May 9, 2012 · 32 revisions

WebPoints Overview

This page contains only general information about WebPoints features. For more info, see:


Kinds of service operations

Each operation should be described through operations property exposed by an instance of Application. The key in this collection represents relative URL. The value represents handler for this URL.

var webpoints = require('webpoints');
var Application = webpoints.Application;
var app = new Application();

app.operations['/opname'] = /*handler*/;

There are three kinds of handlers.

File Hosting

Static hosting exposes the content of the specified folder.

app.operations['/files'] = '~/html';
//-or-
var StaticFilesEndpoint = webpoints.StaticFilesEndpoint;
app.operations['/files'] = new StaticFilesEndpoint('~/html', {maxAge: 3000});

Each file in the folder is accessible by its name.

Custom handler

Custom handler is similar to HTTP request handler in Express.

app.operations['/hw'] = function(request, response){ response.send('Hello, world!'); }

Classic Express-like programming as you expect.

Service operation

This way is oriented on declarative-like operation description.

app.operations['/hw'] = {
  method: 'get',
  params: {},
  handler: function(callback){ callback("Hello, world!"); }
};

Description of service operation schema:

{
  method: 'get', //can be 'get', 'post', 'put', 'delete'
  params: {name: {}}, //description of parameters. The key represents name of the parameter. Order of fields is significant
  handler: function(..., callback){}, // a function that implements business logic
  serialize: true, //can be true, false or function. OPTIONAL
  middleware: [] //an array of Express middlewares for this endpoint
}

Service Operation parameters

Service operation parameters should be specified in the same order as handler parameters. The name of the parameter is used to request it using request.param Express function. The schema of the parameter description:

{
  'default': 12, //Default value of the parameter. If it is specified then parameter is optional. OPTIONAL.
  deserialize: true|false|function(value){}, //true to deserialize parameter value represented by JSON string, false to return parameter as string, function to apply custom deserialization. OPTIONAL.
  isHeader: true | false, //read parameter from header. OPTIONAL.
  schema: {}, //JSON schema that describes type of the parameter value. OPTIONAL.
}

If default value is not specified and HTTP request doesn't contain the parameter then WebPoints returns HTTP 400 status.

Templates

You can use predefine templates for describing parameters. They are located in parameters property of the WebPoints module.

  • Primitive(t, defval) - parameter with the specified primitive type. Possible values for t are 'string', 'number', 'integer', 'boolean', 'any', 'null', 'object', 'array', Array, Object, Number, String, null. THe second parameter accepts default value(optionally);
    • NumberParam(defval) - numeric parameter;
    • StringParam(defval) - string parameter;
    • IntegerParam(defval) - integer parameter;
    • BoolParam(defval) - boolean parameter;
    • NullParam() - null value expected;
    • UnionParam(type1, type2, ...., typeN) - union of types;

The following code demonstrates how to use these templates:

var webpoints = require('webpoints');
var Application = webpoints .Application, NumberParam = webpoints .parameters.NumberParam;
var app = new Application();
app.operations['/sum'] = {
  params: {a: new NumberParam(), b: new NumberParam()},
  handler: function(a, b, callback) { }
};

Operation handler

The service operation handler implements RESTful service operation logic. WebPoints infrastructure automatically passes the arguments to this function. The last parameter of the handler should be callback that is used to return value from the function.

app.operations['/sum'] = {
  params: {a: {'default': null}, b: {deserialize: true}},
  handler: function(a, b, callback) { }
};

this object of the handler function always points to the operation context. This object inherits all fields from the WebPoints environment object, plus the following fields:

  • request - HTTP request;

The environment can be specified through WebPoints application constructor:

var app = new Application({str: 'Hello, world'});
app.operations['/sum'] = {
  params: {},
  handler: function(callback){ callback(this.str); }
};

The possible signatures of the callback:

function(str, [statusCode], [headers]) //put str into the HTTP body.
function(obj, [statusCode], [headers]) //converts obj into JSON format

Response serialization

Handler return value can be passed back to the client as string in the HTTP body, JSON value or custom formatter string. This behavior is controlled by serialize field.

  • true - serialize response as JSON;
  • false - pass result as string. This is a default option;
  • function(value) - custom serialization of the value. this of the function references to HTTP response object.

Response callback provider

The callback used by handler is constructed using createResponseCallback function accessible from Application instance.

createResponseCallback(operation, response) returns Function

The first argument contains reference to the operation descriptor. The second argument references HTTP response. The callback provider should returns a function that passes as callback to the handler. The following code demonsrates how to override the standard callback:

var Application = require('webpoints').Application;
var app = new Application();
app.createResponseCallback = function(operation, response){
  return function(value, statuscode){ this.send(value, statuscode); }.bind(response);
};

Operation provider

Each value of in the operations object handling by createOperation function provided through Application instance.

createOperation(url, operation, express)

This function should add the URL handler to the Express application. url is an relative URL to the function. operation is an value that describes the service operation.


Describing operations in the separated file

The service operations can be placed into the separated file and loaded with operations.load function:

//operations.js file
exports['/sum'] = {
  method: 'get',
  params: {x: {schema: {type: 'number'}}, y: {schema: {type: 'number'}}},
  handler: function(x, y, callback){ callback(x + y); }
};
//server.js file
var Application = require('webpoints').Application;
var app = new Application();
app.operations.load('./operations.js');

Express middleware

It is possible to attach ExpressJS middleware to the endpoint.

var express = require('express');

app.operations['/put'] = {
  method: 'put',
  params: {x: {deserialize: true}, y: {deserialize: true}},
  handler: function(x, y, callback) { },
  middleware: [express.bodyParser()]
};
Something went wrong with that request. Please try again.