A connect-compatible middleware for status responses on JSON HTTP APIs
Json-status is a node.js library that makes JSON status and error messages simpler and more consistent.
If you use the middleware, you'll be able to give consistent json responses for all kinds of different HTTP status code scenarios:
eg This code:
resstatusnotFound"couldn't find that object";
...will respond with a json string like so:
error :type : 404message : "Not found"detail : "couldn't find that object"
npm install json-status --save
var JsonStatus = require'json-status';var connect = require'connect';var server = connectcreateServer;var statusMiddleware = JsonStatusconnectMiddlewareconsole.log"error: " datatype datamessage datadetail;;serverusestatusMiddleware;serveruseresstatusinternalServerError"fake error!"; // this will respond with a 500;
var JsonStatus = require'json-status';var http = require'http';httpcreateServerreq resinternalServerError"fake error too!";listen1337 '127.0.0.1';
To understand what the HTTP status codes mean, please refer to http://www.w3.org/Protocols/rfc2616/rfc2616-sec10.html.
This method takes an
options object and returns a connect-compatible middleware, ready to be
use()ed in a connect/express application.
var statusMiddleware = JsonStatusconnectMiddlewarenamespace : "status"quiet500 : trueconsole.log"error: " datatype datamessage datadetail;;serverusestatusMiddleware;
The options object is actually optional, as are all its properties. You can modify how the middleware behaves through these properties though:
namespace (string) : dictate the name that will be used to add json-status to a response object.
eg, if you do this:
var statusMiddleware = JsonStatusconnectMiddlewarenamespace : "blah";
The json-status object will be usable in a request handler like this:
resblahinternalServerError"something bad happened";
The default value is "status".
quiet500 (boolean): turn on 'quiet500' mode, meaning that the details of a 500 error will be suppressed.
eg, for this code:
resstatusinternalServerError"something bad happened";
The response will be this if quiet500 is true:
error :type : 500message : "Internal Server Error"
The response will be this if quiet500 is unset or false:
error :type : 500message : "Internal Server Error"detail : "something bad happened"
quiet500 mode is nice on production systems where you don't necessarily want your users to know exactly what went wrong on an internal server error, but you still want to provide the details for logging purposes.
onError (function): pass a callback that takes an error object as its only parameter in order to have that callback called on every 4xx or 5xx status code. The error object will have
detail parameters on it. This is really useful for logging and/or metrics.
These methods generally set the HTTP status and end the response, so in general you should not expect to write more to the response after these. If a response body makes sense, it will generally be written automatically. For clarity, it's recommended that when you call
one of these functions, you call it with
return in front of it. Here's an example:
Here are the functions that it makes available in your method handler:
This method is used for HTTP STATUS 201 scenarios when the server has just created a resource successfully so that the server can tell the client where to find it. It sets the status to 201 and sets the 'Location' header to the redirectUrl. An optional second parameter can additionally be sent to be stringified as the response body.
This method is used for HTTP STATUS 301 scenarios where a resource has been permanently moved somewhere else so the server can tell the client where to find it. It sets the status to 301 and sets the 'Location' header to the redirectUrl.
This is just an alias of movedPermanently()
"200 OK" statuses are the default, so you don't need to specify those explicitly.
201 Created statuses are described in the redirect section above.
Used to indicate that a response has been accepted, but not yet processed, this response will emit a "202 Accepted" status.
Used to indicate that a request was successful, but there's no body to return (for example, a successful DELETE). This response will emit a "204 No Content" status.
Used to indicate that a request was sucessful so a related UI (usually a form) should clear its content. This response will emit a "205 Reset Content" status.
All of the error scenarios are handled similarly and attempt to show a response body that indicates the error that occurred as well. The status code will be set on the response as well as in that response body.
All of these methods additionally take a single parameter where additional detail information can be added. For example:
serverroute'/'return resstatusinternalServerError'The server is on fire.';;
"type":500"message":"Internal Server Error""detail":"The server is on fire"
"type":405"message":"Method Not Allowed"
"type":413"message":"'Request Entity Too Large"
"type":414"message":"Request URI Too Long"
"type":415"message":"Unsupported Media Type"
"type":429"message":"Too Many Requests"
"type":500"message":"Internal Server Error"