bubble-serv
Express middleware for fast prototyping JSON server (JSON-based REST api). Mainly intended for mock servers, tests, prototypes.
Just put authorized.json
file into user/
folder, and you will get user/authorized
method in your API, wich returns content of file. Add authorized.post.json
for separate response on POST request. You can use .js
instead of .json
for more complex response, in case you want to take into consideration query params, body content or path params.
Installation
npm install bubble-serv
Usage
var express = require('express');var app = express();var bodyParser = require('body-parser'); // is not a part of this bundlevar bubbleServ = require("bubble-serv"); // if body params will be usedapp.use(bodyParser.json()); app.use( '/api', bubbleServ({apiRoot: "api-files",}) ); // start serverapp.listen(3000);
Put file info.json
into api-files/
folder. Open with browser URI: localhost:3000/api/info
- you will get content of info.json
.
POST, PUT, etc
Add prefix to file extension with http method name in lower case, and file will be served only for this http method. info.post.json
will be served only to POST localhost:3000/info
. Files without http-method prefix are used to any kind of http methods.
Resolving file path
When bubble-serv gets request POST user/info
it try to find file by following sequence (similar to node "require" algorithm):
first with ".post" prefix by standard "node" sequence
user/info/index.post.js
first with ".post" prefixuser/info/index.post.json
.js has priority to .jsonuser/info.post.js
user/info.post.json
then without prefix
user/info/index.js
the same, but without ".post" prefixuser/info/index.json
user/info.js
user/info.json
Bubbling
If nothing is found it bubbles up in folder tree. It creates path param "info"
and goes up to folder user/
, trying to find user/index.post.js
with regular algorithm, etc.
Thus, if we have one file index.js
in folder user
, all request like user/id/some-params/and-more
will be delegated to this user/index.js
. Bubble-serv will generates pathParams
for it: ["id", "some-params", "and-more"]
during bubbling.
Using .js file to handle params. Context
To handle request parameters you have to export callback function from your .js file, for example user/index.js
:
module.exports = function(context, request, response){ return {...context}; // response content, sent to browser}
request
and response
are regular express request/response objects. In request
object bubbleServ
property contains context
data, which is used as a first argument for callback.
Context
Context is an object with data, useful to handle request:
queryParams | string|object | Parsed query params - url encoded params after "?" sign |
bodyParams | object | If body-parser middleware is installed, request.body property will be copied here |
pathParams | string[] | Array of folder names generated during bubblind. If you have "user/index.js" file and request was "user/10/address/city". pathParams = ["10", "address", "city"] for file "user/index.js". |
Some additional data:
apiRoot | string | Folder name with API files, according to express project root |
apiAbsRoot | string | Absolute path to API root |
parsedUrl | ParsedUrl | { protocol, slashes, auth, host, port, hostname, hash, search, query, pathname, path, href } |
requestedPath | string | |
resolvedScript | string | Absolute path to script which is resolved to handle current request (current file absolute path) |
Options
Prop | Type | Default | Description |
---|---|---|---|
apiRoot | string | "./" | Folder name with API files, according to express project root |
traceLabel | string | "BUBBLE SERV" | Prefix for console messages. If NULL or empty string, no messages will be printed to console |
traceScriptResolving | boolean | false | If traceLabel is set, and traceScriptResolving=TRUE, then details of working script searhing will be printed to console |
extractPath | function(req) => string | null | Must return string - path to api method. If Null - URI path will be taken. Can be useful if RPC is used instead of REST |
mapError | function(error, req, res) => any | null | Format error function. Default error format is: {error: string, message: string} |
mapResult: | function(result, req, res) => any | null | Format response function. Default is pure result (content of file) in JSON format. Useful for common wrappers, transports as JSON-RPC 2.0 wrapper |
Sample API
How to create sample API is described in sample.md
CORS (net::ERR_CONNECTION_REFUSED)
With Javascript in browser, when your script tries to fetch API from another domain, you can get connection error. This situation is called Cross-Origin Resource Sharing (CORS). Server have to send specific http headers to allow browser to read API. The best way is to use additional express middleware, such as cors.