Express middleware and fluent API to standardize REST API responses and error formatting to make your life simple again.
npm install express-stdresponse
Response body normalization is important. API routes need to be able to return error codes and extended logging info in a standardized and consistent way across your API's. express-response exposes a simple response model that your routes can use that will allow you to:
-
attach error to response with your own unique error code and custom description.
-
attach multiple errors to response (instead of a generic 400 Bad Request, you can return an error collection with descriptive validation errors for each parameter)
-
attach info objects with any response (successful or error responses).
-
automatically catch and include any unhandled errors
-
make failures transparent and responses beautiful
{
"errors": [
{
"status": 400,
"code": "Bad Request",
"desc": "the request body was missing or malformed",
"errors": [
{ "status": 400, "code": "MISSING_USERID", "desc": "missing userId" },
{ "status": 400, "code": "MISSING_PRODUCTID", "desc": "missing productId" }
],
"info": [
{ "desc": "customer object did not include id, will assume insert" }
]
}
]
}
If you are using express.js there are 2 ways to use express-response. The preferred method is the response resolver. Its a wrapper method which handles all promise resolution, errors, and response normalization.
- Use the response resolver for your routes eg.
const app = require('express').express();
const resolve = require('express-stdresponse').response;
app.get('/', resolve( response => 'ok!' ));
- Use express middleware eg.
const app = require('express').express();
const Response = require('express-stdresponse').Response;
Response.registerExpressMiddleware(app)
app.get('/', (req,res) => 'ok!' );
const express = require('express');
const app = express();
const resolve = require('express-stdresponse').response;
app.get('/success', resolve(response => {
return 'ok!'; // returns { "result": "ok!" }
}));
app.get('/error', resolve(response =>{
throw new Error('err!'); // returns {"errors":[{"status":500,"desc":"err!",data:"<stacktrace>"}]}
}))
// or add results, errors, and information to response as needed
app.get('/', response((response, req, res, next) => {
if (req.query.throwError) response.error('an error');
if (req.query.returnInfo) response.information('some info');
response.results(req.query);
// returns {"errors":[{"status":500,"desc":"an error"}],"info":[{"desc":"some info"}],"result":{"a":1,"b":2,"c":3}}
return response;
}));
const server = app.listen(3000, function () {
console.log('Example app listening at port %s', server.address().port);
});
For more detailed usage examples check out the unit tests in /tests
- response.hasError - returns true if any errors have been attached to the response model
- response.statusCode - returns the highest value http status code in the response error collection or 200 if no errors have been attached to the response model
- response.hasInfo
- response.hasResult
Used to attach errors to the response body. Returns reference of inserted error model. Supports chaining.
- response.error( (string) description )
- response.error( (string) error_code, (string) description )
- response.error( (int) status_code, (string) error_code, (string) description )
- response.error( (int) status_code, (string) error_code, (string) description, (object) metadata )
- response.error( (string) error_code, (string) description, (object) metadata )
- response.error( (Error) error_object )
- response.error( (object) options_object )
- response.error( [ (object) options_object] )
Used to attach info to the response body. Returns reference of inserted info model. Supports chaining.
- response.information( (string) description )
- response.information( (string) error_code, (string) description )
- response.information( (int) status_code, (string) error_code, (string) description )
- response.information( (int) status_code, (string) error_code, (string) description, (object) metadata )
- response.information( (string) error_code, (string) description, (object) metadata )
- response.information( (object) options_object )
- response.information( [ (object) options_object] )
Used to attach your actual response body payload for successful requests
- response.results( (any) your_response_body_payload )
- response.setResult( (any) your_response_body_payload )
Helper methods to create/attach common errors
- response.errorGatewayTimeout(description, metadata)
- response.errorInternalServerError(description, metadata)
- response.errorBadRequest(description, metadata)
- response.errorTooEarly(description, metadata)
- response.errorMethodNotAllowed(description, metadata)
- response.errorForbidden(description, metadata)
- config.REPORT_UNHANDLED_ERRORS: true
- config.REPORT_UNHANDLED_ERRORS_INCLUDE_STACKTRACE: true
- config.DEFAULT_ERROR_HTTP_STATUS_CODE: 500
- config.DEFAULT_SUCCESS_HTTP_STATUS_CODE: 200