Skip to content

Handler for Express 4 application, which allows to perform batch requests.

License

Notifications You must be signed in to change notification settings

yarikos/express-batch

Folders and files

NameName
Last commit message
Last commit date

Latest commit

 

History

71 Commits
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 

Repository files navigation

express-batch

Build Status Test Coverage Code Climate NPM Downloads License Known Vulnerabilities

Description

Middleware for Express 4.x that allows for batched API requests.

It's attached as a handler for a particular route.

If you need to perform several different requests to one API simultaneously, you could combine them all together (in one querystring) and send only one request to the handler's route.

The handler parses requests, and then invokes the relevant handler for each request (the standard app router is used), collects all the responses and sends them back as a JSON object with sections for each response.

Currently, only routes for GET locations are supported.

Example

// app init
var express = require("express");
var expressBatch = require("express-batch");
var app = express();

// mount batch middeleware
app.use("/api/batch", expressBatch(app));


// mount ordinary API endpoints
app.get("/api/constants/pi", function apiUserHandler(req, res) {
    res.send(Math.PI);
});

app.get("/api/users/:id", function apiUserHandler(req, res) {
    res.json({
        id: req.params.id,
        name: "Alice"
    });
});

// start the app
app.listen(3000);

This example in code.

With this example, a request to http://localhost:3000/api/batch?users=/api/users/49&pi=api/constants/pi&nonexistent=/not/existent/route will return:

{
    users: {
        result: {
            id: "49",
            name: "Alice"
        },
        status: 200
    },
    pi: {
        result: 3.141592653589793,
        status: 200
    },
    nonexistent: {
        result: "Not Found",
        status: 404
    }
}

It is also possible to have nested field-value pairs by passing in an options argument with a custom separator property.

// mount batch handler with optional separator for nested field-value pairs
var options = {
    separator: ';'
};
app.use("/api/batch", expressBatch(app, options));

// easily handle batched requests with deep field-value pairs
app.get("/api/climate/", function apiClimateHandler(req, res) {
    var response = {
        sunny: false,
        warm: false
    };

    // e.g., with a request path of 'api/batch?climate=/api/climate/?sunny=true&warm=true'
    if (req.query.sunny === 'true' && req.query.warm === 'true') {
        response.sunny = true;
        response.warm = true;
    }
    res.json(response);
});

Limitations

  • Tested only with Express 4
  • Supports only routes for GET requests.
  • Handlers which will bу used beyond the middleware, could use only these methods of response:
    • res.json()
    • res.jsonp()
    • res.jsonp()
    • res.end()
    • res.status()
    • res.sendStatus()
    • res.sendStatus()
    • res.setHeader()
    • assign value to res.statusCode

Notes

There are similar packages, but which work using real http requests:

Todo

  • Returning headers in batch results
  • Add documentation about headers passing
  • Support of arrays (batch?users=/api/users/1&users=/api/users/2 should return users: [{id:1}, {id:2}])
  • Support of rest of HTTP methods
  • Support of rest of response methods

License

MIT

============= Gitter Bitdeli Badge