HTTP-PROBLEM
Provides a simple implementation of the HTTP Problem Spec (JSON format only).
See: https://tools.ietf.org/html/draft-ietf-appsawg-http-problem
Note: Use v0.1.0 for Node v0.12.x. With v0.2.0, the code starts to make use of newer ES6 features.
npm install http-problem
Nothing really all that fancy here. There are a few ways to create a problem object:
The following creates a simple default problem for an HTTP status code
var Problem = ;var badrequest = ProblemBADREQUEST;throw badrequest;
You can define then throw your own problem types:
var NoCreditType = 'http://example.com/probs/out-of-credit' 'You do not have enough credit.' status:400; NoCreditType;
Standard connect middleware is provided. The middleware intercepts Problem objects thrown as exceptions and serializes them appropriately in the HTTP response.
var express = ;var server = ; var router = express;router;router;server;
Use the problem.wrap
method to parse out a received problem:
var Problem = ; var obj = type: 'http://example.org' status: 400; var problem = problem; // orvar str = JSON;problem = problem; // wrap from string
API
Problem([type][, options])
Constructor: Constructor for new Problem instances
type
- either a Problem.Type instance or string with an absolute URL. Defaults toProblem.BLANK
if unspecified. identifying the erroroptions
status
- HTTP Status Codedetail
- Human readable explanation of the problem that is specific to this instance.instance
- An Absolute URL identifying the specific occurence of the problem.
Additional extension properties may be included as values on the options
. When passed, these will become constant
values on the generated Problem object
<string> Problem.prototype.type
Property: Returns an absolute URL identifying the Problem type.
<string> Problem.prototype.title
Property: Returns the Problem title.
<number> Problem.prototype.status
Property: Returns the HTTP Status code for this problem.
<string> Problem.prototype.detail
Property: Returns a human readable explanation specific to this instance of the problem.
<string> Problem.prototype.instance
Property: Returns an absolute URL identifying the specific occurence of the problem.
<void> Problem.prototype.send(res)
Method: Sends the Problem on the HTTP Response. The res
parameter is
assumed to be an Express-style response object. The implementation of the send
method is:
function(res) {
var status = this.status || 400;
res.setHeader('Content-Type', 'application/problem+json');
res.status(status).json(this);
};
<constructor> Problem.create()
Class Method: Create a new Problem class, allowing you to create your own Problem subclasses.
var MyProblem = Problem.create();
var myProblem = new MyProblem(Problem.BLANK);
myProblem.throw();
<boolean> Problem.registerProblemType(type)
Class Method: Register a custom Problem.Type
var NoCreditType =
new Problem.Type(
'http://example.com/probs/out-of-credit',
'You do not have enough credit.',
{status:400});
Problem.registerProblemType(NoCreditType);
<boolean> Problem.registerProblemType(uri[, title])
Class Method: Register a custom Problem.Type
Problem.registerProblemType(
'http://example.com/probs/out-of-credit',
'You do not have enough credit.');
<Problem.Type> Problem.lookupProblemType(uri)
Class Method: Lookup a registered custom Problem.Type
<Problem.Type> Problem.forStatus(status)
Class Method: Lookup the Problem.Type
for a specific HTTP status code
<Problem> Problem.wrap(obj)
Class Method: Wrap a JavaScript object as a Problem.
<Problem> Problem.wrap(str)
Class Method: Parse the JSON string and wrap the resulting object as a Problem.
<function> Problem.middleware
Class Property: Connect style middleware that can be used to intercept Problems thrown as errors and serialize them correctly on an HTTP response.
var express = ;var server = ; var router = express;router;router;server;
Problem.Type(url[, title][, options])
Constructor: Creates a new Problem.Type
.
url
- The absolute URL identifying the problem type.title
- The common title of the proble.options
-status
- The default HTTP status code for problems of this type.ins
- The instance constructor for problems of this type.
var MyType = new Problem.Type(
'http://example.org', 'MyProblem', {status:400});
MyType.throw();
<string> Problem.Type.prototype.type
Property: The absolute URL identifying the problem type.
<string> Problem.Type.prototype.title
Property: The common title of the problem type.
<number> Problem.Type.prototype.status
Property: The default HTTP status code for problems of this type.
<void> Problem.Type.prototype.throw([options])
Method: Create a new instance of this problem type and throw it as an
Error. The options
argument is the same as the options
for
the Problem
constructor.
<Problem> Problem.Type.prototype.raise([options])
Method: Create a new instance of this problem type and return it. The
options
argument is the same as the options
for the
Problem
constructor.
<void> Problem.Type.prototype.reject([options])
Method: Create a new instance of this problem type and create a rejected
Promise with the Error. The options
argument is the same as the
options
for the Problem
constructor.
Constants:
<Problem.Type> Problem.BLANK
- Theabout:blank
Problem Type<Problem.Type> Problem.OK
<Problem.Type> Problem.CREATED
<Problem.Type> Problem.ACCEPTED
<Problem.Type> Problem.NON_AUTHORITATIVE_INFORMATION
<Problem.Type> Problem.NO_CONTENT
<Problem.Type> Problem.RESET_CONTENT
<Problem.Type> Problem.PARTIAL_CONTENT
<Problem.Type> Problem.MULTIPLE_CHOICES
<Problem.Type> Problem.MOVED_PERMANENTLY
<Problem.Type> Problem.FOUND
<Problem.Type> Problem.SEE_OTHER
<Problem.Type> Problem.NOT_MODIFIED
<Problem.Type> Problem.USE_PROXY
<Problem.Type> Problem.TEMPORARY_REDIRECT
<Problem.Type> Problem.BAD_REQUEST
<Problem.Type> Problem.UNAUTHORIZED
<Problem.Type> Problem.PAYMENT_REQUIRED
<Problem.Type> Problem.FORBIDDEN
<Problem.Type> Problem.NOT_FOUND
<Problem.Type> Problem.METHOD_NOT_ALLOWED
<Problem.Type> Problem.NOT_ACCEPTABLE
<Problem.Type> Problem.PROXY_AUTHENTICATION_REQUIRED
<Problem.Type> Problem.REQUEST_TIMEOUT
<Problem.Type> Problem.CONFLICT
<Problem.Type> Problem.GONE
<Problem.Type> Problem.LENGTH_REQUIRED
<Problem.Type> Problem.PRECONDITION_FAILED
<Problem.Type> Problem.REQUEST_ENTITY_TOO_LARGE
<Problem.Type> Problem.REQUEST_URI_TOO_LONG
<Problem.Type> Problem.UNSUPPORTED_MEDIA_TYPE
<Problem.Type> Problem.REQUESTED_RANGE_NOT_SATISFIABLE
<Problem.Type> Problem.EXPECTATION_FAILED
<Problem.Type> Problem.UNPROCESSABLE_ENTITY
<Problem.Type> Problem.TOO_MANY_REQUESTS
<Problem.Type> Problem.INTERNAL_SERVER_ERROR
<Problem.Type> Problem. NOT_IMPLEMENTED
<Problem.Type> Problem.BAD_GATEWAY
<Problem.Type> Problem.SERVICE_UNAVAILABLE
<Problem.Type> Problem.GATEWAY_TIMEOUT
<Problem.Type> Problem.HTTP_VERSION_NOT_SUPPORTED