PASAR

Promise Aware Smart API REST builder to easily implement Express routers with advanced capabilities.

Índex

• Abstract
  • Definitions
  • Notes
• Features
  • Basic
  • Advanced
  • More...
• Documentation
• Examples
• TO-DO list
• Contributing

Abstract

PASAR main goal is to asist you in building consistent and full-featured promise-based APIs focusing in your business logic and not bothering about plumbing details.

To achieve it, PASAR proposes a clear and consistent routing schema with a few conventions to achieve orthogonal feature access.

That is: To build a full featured API REST, you only need to provide one or two things:

• A list of (route-) named API function specifications (which, to avoid confusion, we will call it "services" or "service definitions" from now on).
• An optional Options object to fine-tune PASAR behaviour.

Example:

1    var Pasar = require("pasar");
2
3    var Options = {
4        // ...
5    };
6
7    var myApi = {
8        myServiceName: {
9            // Service definition.
10        },
11        // ...
12    };
13
14    module.exports = Pasar(myApi, Options);

Service definitions consists in an object with one or more attributes. Simples't service definition looks like:

1    myServiceName: {
2        _all: function myActionFunction(input, ac) { // Use _get, _post, etc.. to attach your handler to specific http method.
3            // input: Your input data. No matter if send by get, post, put, etc...
4            //     ...but you can fine-tune this by overridding default request mapper.
5            // auth: FIXME: Document it!!.
6
7            return new Pasar.Promise(function(resolve, reject) {
8                // Do some (async) logic...
9
10                // ...and finally:
11                resolve(someData);
12                // ...or:
13                reject(reason);
14            });
15        },
16    },

If your API grows too much, you can provide an array of smaller service definiton sets instead of single one. Ex.:

1
2    var myApi = [
3        requere("path1/sumbmodule1.js", // Services defined in other module.
4        requere("path2/sumbmodule2.js", // More modularyzed services...
5        { // And of course, some others can be defined directly here...
6            myServiceName: {
7                // Service definition.
8            },
9            // ...
10        }
11    ];
12

Action functions are expected to return a promise but they are actually able to directly return a result (which is automatically promisified).

On promise rejections (or thrown errors) an http 500 error code (Internal Server Error) is send to the client and, from version 1.2.14, if logErrors option is not set to false, the error/rejection message is logged to stderr (except ).

(See more complete examples later...)

Definitions

Service : With "Service" we mean any functionality attached to unique url of our API no matter which methods (get, post...) attends or not.

Service Definition : Javascript object providing all functions needed to implement all available methods of service and some other optional properties which lets us to change service behaviour in any manner.

Actions : Actions (or Action Handlers) are functions attached to _get, _post, _put, _delete or _all properties of a Service Definition. They are expected to return a promise of the result data. But, if don't, it's actual result will be automatically promisified.

Request Mapper : A Request Mapper is a function responsible to receive the request object and a second parameter with the actual method name and return propper input for the Action Handler. This pattern let's us to access exactly same functionality implementations thouth http as a REST API, or locally as library functions.

Response Mapper : Response Mappers are the counterpart of Request Mappers. They receives the promise returned by Actions and perform proper http response (We probably should never override default one).

Facility : Facilities are fully automated extra functionalities over all Services (accessed thought serviceUrl/facilityName) and/or over the whole API (accessed thought /facilityName/. The only currently implemented facility is /help.

Output Filters : Output Filters (or Output Formatters) let all our services output to be exported to distinct output formats, such as csv, html, etc... SIMPLY adding corresponding extension (.csv, .html...) to the original service url.

Notes

POST / PUT / DELETE processing:

PASAR does not implement POST processings itself. Instead expects proper middlewares to be used by our app. (If they are not used, POST (or PUT / DELETE) data will not be detected). This middlewares are:

• body-parser: For regular url-encoded or json requests. Examples:

  app.use(bodyParser.urlencoded({ extended: false })); app.use(bodyParser.json());

• express-fileupload: For multipart requests (Ex with forms like <form enctype="multipart/form-data" ...>).

  app.use(fileUpload());

Misc:

• We can attach same function to any of the _get, _post, _put and/or _delete or simply to _all (which attaches it to all methods except explicitly specified thought _get, _post, etc...). But actions never knows about actual requested method. So, if we want different behaviour, for example, in GET requests than in POST ones, we should specify our own Request Mapper to provide propper Action input depending on the actual request method.

Features

Basic Features

• Easy method (GET, POST, etc...) attachment handling.

• Multiple output formats selected by extension (default is .json). Including html (to easy data inspection).

  • .json
  • .html
  • .csv
  • .xlsx
  • and more comming soon...

• Easy access to self explanation (adding '/help' to each url) and fully automated help index.

  • As simple as supplying single help string.
  • Or as powerful as supplying fully detailed object including method details, examples, etc...
  • Ability to enable examples to be directly triggered from help page (easy checking).
  • Always list all implemented methods even undocumented and, if documented, also unimplemented ones marking them as "undocumented".
  • Fully automated help index (on root's /help) even for undocumented functions.

• Consistent routing schema:

  • /myRoute -> Default output (JSON) of your service.
  • /myRoute.ext -> Export to "ext" format thought provided output format filters.
  • /myRoute/someId, /myRoute/someId.ext -> Same passing some id...
  • /myRoute/facilityName -> Access to specified facility (/help, /form /test...)
  • /facilityName -> Access to specified facility index (if applies). For example:
    • /help: Help index.
    • /test: Run all tests (not yet implemented).

• Global, per-api, per-service and per-method configurable timeouts (via promise rejection).

• Internally reusable: Services implementation can easily make use of other functions.

  • Method handlers receive JSON object with request parameters NOT request, nor response or next express objects.
  • Also, they are expected to return promises, not actual data or, even less, to deal with http handshaking.
  • From v1.1.7, they also can be directly called as this.srvName.method() from other service methods.
    • NOTE:remember to use var me=this trick when needed.

• Externally reusable: All service actions are externally exposed thought 'fn' property of the resulting router.

  • I.E.: myRouter.fn.someFunction.get({...}); // will call that method handler directly.
  • If it has only one available method definition (even if it is 'all'), simply: myRouter.fn.someFunction({...});
  • Also, you can use all available output filters. Example: myRouter.fn["someFunction.html"].get({...});

• Externally reusable SYNCHRONOUSLY: Just like 'fn', router is provided with 'syncFn' vector providing sync versions of your service actions (Available only for Node version v0.11.0 or hihger).

  • This enables you to reuse simple functionalities as sync functions.
  • But be carefull, that THOSE ARE BLOCKING FUNCTIONS. So use at your own risk.

• Easy querying while developing with automated (but customizable) '/form' facilities.

  • Accepting 'json' as input field type (being the default if unspecified).
  • With 'select' combo-boxes options feedable thought API requests:
    • Examples (Pug):
      • option(data-from="someApiFn")
      • option(data-from="someOthesApiFn", data-path="foo.bar.baz", data-key="keyFld", data-value="descFld")
  • Integrated response view (thought html output filter) for inspection.
  • Download capability for all available output filters.

Advanced Features

• Advanced access control policies:

  • Including restriction to some functionalities like /help, etc...
  • NOT authentication itself. · You can use your own user authentication method like passport (https://www.npmjs.com/package/passport) or your own implementation. · Then, use that and other information to implement your own access control policies. · See "Default Authentication Handler implementation" in auth.js library for more detailed explanation.

• Custom request mapping:

  • Method handler input is, by default, JSON which is mapped thought predefined callback.
  • You can specify your own one customized for specific or 'all' methods.
  • Example:

  requestMapper: myRequestMapper,

...for more details about how to implement your own request mapper, see default Request Mapper implementation.

• Custom response mapping:

  • Method handler output is always expected to be a promise of object containing actual result.
  • This result is redirected to http response by default thought predefined response mapping callback.
  • You can specify your own one customized for specific or 'all' methods.
  • Example:

  responseMapper: myResponseMapper,

...for more details about how to implement your own response mapper, see default Response Mapper implementation.

More...

• More comming... (see TODO )

• For latest changes see: CHANGELOG

Documentation

Currently the only existing documentation consist in below examples and an incomplete Usage Manual.

Maybe you would like to help in building better one... (see Contributing)

Examples

Below are documentary examples. If you need fully functional examples see PASAR demos.

All API definitions should look's like follows:

1    var Promise = require("promise"); // Or your favorite promise library.
2    var Pasar = require("pasar");
3
4    var Options = { // Comment-out / modify as you need...
5        // logErrors: false,                            // ...to disable rejection logging.
6        // noLib: true,                                 // ...to disable .fn and .syncFn facilites.
7        // noHelp: true,                                // ...to disable /help facilities.
8        // noForm: true,                                // ...to disable /form facilities.
9        // noFilters: true,                             // ...to disable optional formatting filters.
10        // "defaults.help.examples.get": [{}],          // ...to automatically provide all your functions help with simple example.
11        // "defaults.authHanlder": myAuthHandler,       // ...to sepcify your own authentication handler.
12        // "defaults.requestMapper": myRequestMapper,   // ...to sepcify your own request mapper.
13        // "defaults.responseMapper": myResponseMapper, // ...to sepcify your own response mapper.
14        // promiseEngine: myPromiseEngine,              // ...to provide your own promise engine.
15        // "client.jQuery": "url_to_jQuery"             // ...to override jQuery path in facility views.
16        // ... (See documentation for more details on available options).
17    };
18
19    var myApi = {
20        someFunction: {
21            _get: function(input) {
22                // Do some stuff...
23                return new Promise(function(resolve, reject) {
24                        // Do some async stuff...
25                        // And somewhere:
26                        resolve({
27                            data: {...}, // Actual function response.
28                            meta: {...}, // Some optional metadata which could be used by many output filteres.
29                                        // i.e. page title, field types, etc...
30                        });
31                        // And in some other place:
32                        reject(error);
33                });
34            },
35            _post: function(input) {
36                // ...
37            },
38            timeout: 3000, // Reject with timeout error if promise is not resolved after 3 seconds.
39                // Or: timeout: {all: 3000},
40                //
41                // NOTE: You can set different timeouts for specific methods (i.e.: "{get:5000, post:3000}")
42                //     ...but this only works if defined separately. Methods defined in block thought _all
43                //     property will only get generic timeout (because it also becomes single express route).
44                //
45                // NOTE 2: You can customize timeout error message passing an array like this:
46                //     timeout: [3000, "Operation taken too long"],
47            help: {
48                contents: "Explain what this function does...",
49                brief: "Brief explanation to be shown in whole API help index",
50                    // If not given, brief will be auto-extracted from contents.
51                methods: {
52                    all: "Method specific explanation", // Default text. I ommitted, defaults to "(Undocumented)".
53                    _get: "Specific explanation for GET method", // 'get' and '_get' are threated the same.
54                    // post: "", // As commented out, it will default to "all" text.
55                    put: "Some future method explanation.", // Will be marked as "UNIMPLEMENTD".
56                    // delete: "", // As commented out and unimplemented, will NOT be shown.
57                },
58                examples: { // (get/_get, post...) Just like methods definitions...
59                    get: [, // Simple GET example without parameters labelled by its url.
60                         {}, // Add example to query without parameters.
61                         ['label', {foo: "bar"}, "Some optional comment"], // Another with parameters.
62                         [null, [bar: "baz"}], // Another auto-labelled example.
63                             // NOTE: All get examples are automatically linked to it's url.
64                             // NOTE 2: Post, put, etc... are actually linked to "#".
65                             //     In (I hope) near future I expect to implement links to them via ajax call (TODO).
66                             // NOTE 3: Simplest get specification is: «get: [{}]»,
67                    ],
68                    post: [
69                        ['Hello', {foo: "bar"}, "long explanation"],
70                        ['World', {foo: "bar"}, "More longer explanation"],
71                    ],
72                    put: [{foo: "bar"}],
73                    // ...
74                },
75            },
76        },
77        someOtherFunction: {
78            _all: function(input) {
79                // Do some stuff...
80                return new Promise(function(resolve, reject) {
81                        // Do some async stuff...
82                        // And somewhere:
83                        resolve({...});
84                            // If no need for metadata and no data vector specified,
85                            // this will be automagically remapped to:
86                            // {
87                            //     data: {...}, // Actual function response.
88                            //     meta: {...}, // Some optional metadata which could be used by many output filteres.
89                            //                 // i.e. page title, field types, etc...
90                            // }
91                            // ...so you can simply resolve with your actual result EXCEPT if it could contain
92                            // a 'data' vector in its root level. In which case you should at least resolve
93                            // with {data:{...}}
94
95                        // And in some other place:
96                        reject(error);
97                });
98            },
99            help: "Explain what this function does..." // Simplest way to specify minimal help text.
100      },
101    };
102    
103    module.exports = Pasar(myApi, Options);
104

Then, to mount your API REST to your Express app or router simply:

1    // Load API definitions:
2    var someAPI = require("__path_to_my_api__");
3    var someOtherAPI = require("__path_to_my_other_api__");
4
5    // REST API usage:
6    // ===============
7
8    // Having your Express app is 'app' variable...
9
10    // To mount your api at /api route:
11    app.use('/api', someAPI);
12    // ...Or symply 'app.use("/api", require("__path_to_my_api__"))'
13
14    // To mount your api at your app root:
15    app.use(someOtherAPI);
16    // ...Or simply 'app.use(require("__path_to_my_other_api__"))'
17
18    // Of course, you also can mount it on existing express router's subpath or root:
19    myRouter.use(...);
20
21
22    // Usage as internal library:
23    // ==========================
24
25    // To access Services as library:
26    someApi.fn.someFunction.get({foo: "bar"})
27        .then(function(data){console.log(data);})
28        .catch(throw)
29    ;
30
31    // Also with available output filters:
32    var resultPromise = somApi.fn["someFunction.html"]({foo: "bar"});
33        // Returns promise (Use .then(), .catch()...)
34        // ".get", ".post", etc... can be ommited when only one method is implemented.
35    // ...Or simply 'var myAsyncLib = require("__path_to_my_api__").fn;'
36
37    // To access Services as sync library:
38    var result = someApi.syncFn.someFunction({foo: "bar"});
39        // WARNING:
40        //      * Sync functions are blocking. Use at your own risk!!
41        //      * They are not availible in Node versions under v0.11.0.
42        //      * In earlier Node versions, it will throw an exception if you try to use it.
43        //      * Not yet tested (sorry) could not properly work even with node v0.11.0 or higher.
44    // ...Or simply 'var mySyncLib = require("__path_to_my_api__").syncFn;'
45

TODO

• Let's use promise rejection to generate valid http error responses.

  • Nowadays rejections generate HTTP 500 (internal server error) unconditionally.
  • Let's provide a way to use rejections to pick propper error codes and even messages to display.

• Make requirement of 'meta' and 'data' vectors in returned data to be configurable.

  • Nowadays it is autodetected: If 'data' vector is present, it is used as actual result and, if 'meta' is present too, it is used as metadata. Else case, whole returning value is used as data assuming no metadata.
  • This behaviour become weird when this structure is not used but returning value could accidentally contain a 'data' vector.
  • To fix this problem, this behaviour will be configurable thought a property called 'usemeta' (or similar).
  • This property will accept three possible values:
    • true: Which will force the use of {meta: ..., data: ...} structure (with 'data' vector being required).
    • false: Direct data returning (without metadata) will be assumed, EVEN 'data' and/or 'meta' vectors present.
    • "auto": For current behaviour.
  • To preserve backward compatibility, "auto" will be the default. But at next major release it will move to false. So starting to globally override it is highly adviced.

• Posibility to execute predefined tests clientside thought /test facilities.

• Configurable logging capabilites (including time measurement).

• Promise-level caching.

• Make it NESTABLE: If another PASAR router is passed instead of service definition:

  • Mount it at that route.
  • Make facility indexes nest too.

• Unified backend (usability + avoid collisions between services and facilities):

  • Unify all facilities into single index mounted at root (/).
  • Move all facility-related routes under double slash route (ex: //help/srv_route)

• WebSocket update events interface (DRAFT).

  • Sometimes data provided by a REST API becomes outdated too shortly.
  • WebSocket update events if enabled, will provide your method handlers with an "update callback" as a second parameter.
  • Then, your method implementation, althought returning promise for whole data, could start watching for future changes.
  • When a change happen, then should call that callback with new data causing websocket update event to be send to client's that support it.
  • Updated data could optionally be send as diff from previous.
  • Update-events, also, will cause cached (promise) responses to be silently updated. So new requests and clients not supporting WebSocket update events, will also benefit of them.

• Client-side javascript library.

  • Will provide javascript client library downloadable thought /client.
  • This library will provide a js API to access server's API-REST functionalities.
  • Also, will integrate support for WebSockete update events transparently handling "diff" packed data.

• Unit testing:

  • Implement unit tests to ensure new changes doesn't broke anything.
  • Move to 0.1.x versions and pass those tests before any commit.

Contributing

If you are interested in contributing with this project, you can do it in many ways:

• Creating and/or mantainig documentation.

• Implementing new features or improving code implementation.

• Reporting bugs and/or fixing it.

• Sending me any other feedback.

• Whatever you like...

Please, contact-me, open issues or send pull-requests thought this project GIT repository