jsonapi-boom
Boom with JSON-api error support.
- JsonApiBoom
- Helper Methods
- HTTP 4xx Errors
JsonApiBoom.badRequest([message], [data])
JsonApiBoom.unauthorized([message], [scheme], [attributes])
JsonApiBoom.forbidden([message], [data])
JsonApiBoom.notFound([message], [data])
JsonApiBoom.methodNotAllowed([message], [data])
JsonApiBoom.notAcceptable([message], [data])
JsonApiBoom.proxyAuthRequired([message], [data])
JsonApiBoom.clientTimeout([message], [data])
JsonApiBoom.conflict([message], [data])
JsonApiBoom.resourceGone([message], [data])
JsonApiBoom.lengthRequired([message], [data])
JsonApiBoom.preconditionFailed([message], [data])
JsonApiBoom.entityTooLarge([message], [data])
JsonApiBoom.uriTooLong([message], [data])
JsonApiBoom.unsupportedMediaType([message], [data])
JsonApiBoom.rangeNotSatisfiable([message], [data])
JsonApiBoom.expectationFailed([message], [data])
JsonApiBoom.badData([message], [data])
JsonApiBoom.locked([message], [data])
JsonApiBoom.preconditionRequired([message], [data])
JsonApiBoom.tooManyRequests([message], [data])
JsonApiBoom.illegal([message], [data])
- HTTP 5xx Errors
- F.A.Q.
JsonApiBoom
boom provides a set of utilities for returning HTTP errors.
jsonapi-boom extends Boom
utilities with a method signature that accepts any JSON-API attributes, and populates the JSON-API attributes on the error payload.
Each utility returns a Boom
error response object (instance of Error
) which includes the following properties:
(See also the JSON-API Specification for Error Objects)
id
- a unique identifier for this particular occurrence of the problem.links
- a links object containing the following members:about
- a link that leads to further details about this particular occurrence of the problem.
status
- the HTTP status code applicable to this problem, expressed as a string value.code
- an application-specific error code, expressed as a string value.title
- a short, human-readable summary of the problem that SHOULD NOT change from occurrence to occurrence of the problem, except for purposes of - `localization.detail
- a human-readable explanation specific to this occurrence of the problem. Like title, this field’s value can be localized.source
- an object containing references to the source of the error, optionally including any of the following members:pointer
- a JSON Pointer [RFC6901] to the associated entity in the request document [e.g. "/data" for a primary data object, or "/data/attributes/title" for a specific attribute].parameter
- a string indicating which URI query parameter caused the error.
meta
- a meta object containing non-standard meta-information about the error.isBoom
- iftrue
, indicates this is aBoom
object instance.isServer
- convenience bool indicating status code >= 500.message
- the error message.output
- the formatted response. Can be directly manipulated after object construction to return a custom error response. Allowed root keys:statusCode
- the HTTP status code (typically 4xx or 5xx).headers
- an object containing any HTTP headers where each key is a header name and value is the header content.payload
- the formatted object used as the response payload (stringified). Can be directly manipulated but any changes will be lost ifreformat()
is called. Any content allowed and by default includes the following content:statusCode
- the HTTP status code, derived fromerror.output.statusCode
.error
- the HTTP status message (e.g. 'Bad Request', 'Internal Server Error') derived fromstatusCode
.message
- the error message derived fromerror.message
.
- inherited
Error
properties.
The JsonApiBoom
object also supports the following method:
reformat()
- rebuildserror.output
using the other object properties.
Options
Each utility can be called with an object containing any of the JSON-API attributes.
var error = JsonApiBoom;
Generates the following response payload:
Methods
Each utility can also be called with the original boom
signature, meaning you can switch boom
for this package for in your existing API and you will obtain mimially JSON-API compliant error objects.
wrap(error, [statusCode], [message])
Decorates an error with the boom properties where:
error
- the error object to wrap. Iferror
is already a boom object, returns back the same object.statusCode
- optional HTTP status code. Defaults to500
.message
- optional message string. If the error already has a message, it adds the message as a prefix. Defaults to no message.
var error = 'Unexpected input';JsonApiBoom;
create(statusCode, [message], [data])
Generates an Error
object with the boom decorations where:
statusCode
- an HTTP error code number. Must be greater or equal 400.message
- optional message string.data
- additional error data set toerror.data
property.
var error = JsonApiBoom;
HTTP 4xx Errors
JsonApiBoom.badRequest([message], [data])
Returns a 400 Bad Request error where:
message
- optional message.data
- optional additional error data.
JsonApiBoom;
Generates the following response payload:
JsonApiBoom.unauthorized([message], [scheme], [attributes])
Returns a 401 Unauthorized error where:
message
- optional message.scheme
can be one of the following:- an authentication scheme name
- an array of string values. These values will be separated by ', ' and set to the 'WWW-Authenticate' header.
attributes
- an object of values to use while setting the 'WWW-Authenticate' header. This value is only used whenscheme
is a string, otherwise it is ignored. Every key/value pair will be included in the 'WWW-Authenticate' in the format of 'key="value"' as well as in the response payload under theattributes
key.null
andundefined
will be replaced with an empty string. Ifattributes
is set,message
will be used as the 'error' segment of the 'WWW-Authenticate' header. Ifmessage
is unset, the 'error' segment of the header will not be present andisMissing
will be true on the error object.
If either scheme
or attributes
are set, the resultant Boom
object will have the 'WWW-Authenticate' header set for the response.
JsonApiBoom;
Generates the following response:
"payload": ,"headers"
JsonApiBoom;
Generates the following response:
"payload": ,"headers"
JsonApiBoom;
Generates the following response:
"payload": ,"headers"
JsonApiBoom.forbidden([message], [data])
Returns a 403 Forbidden error where:
message
- optional message.data
- optional additional error data.
JsonApiBoom;
Generates the following response payload:
JsonApiBoom.notFound([message], [data])
Returns a 404 Not Found error where:
message
- optional message.data
- optional additional error data.
JsonApiBoom;
Generates the following response payload:
JsonApiBoom.methodNotAllowed([message], [data])
Returns a 405 Method Not Allowed error where:
message
- optional message.data
- optional additional error data.
JsonApiBoom;
Generates the following response payload:
JsonApiBoom.notAcceptable([message], [data])
Returns a 406 Not Acceptable error where:
message
- optional message.data
- optional additional error data.
JsonApiBoom;
Generates the following response payload:
JsonApiBoom.proxyAuthRequired([message], [data])
Returns a 407 Proxy Authentication Required error where:
message
- optional message.data
- optional additional error data.
JsonApiBoom;
Generates the following response payload:
JsonApiBoom.clientTimeout([message], [data])
Returns a 408 Request Time-out error where:
message
- optional message.data
- optional additional error data.
JsonApiBoom;
Generates the following response payload:
JsonApiBoom.conflict([message], [data])
Returns a 409 Conflict error where:
message
- optional message.data
- optional additional error data.
JsonApiBoom;
Generates the following response payload:
JsonApiBoom.resourceGone([message], [data])
Returns a 410 Gone error where:
message
- optional message.data
- optional additional error data.
JsonApiBoom;
Generates the following response payload:
JsonApiBoom.lengthRequired([message], [data])
Returns a 411 Length Required error where:
message
- optional message.data
- optional additional error data.
JsonApiBoom;
Generates the following response payload:
JsonApiBoom.preconditionFailed([message], [data])
Returns a 412 Precondition Failed error where:
message
- optional message.data
- optional additional error data.
JsonApiBoom;
Generates the following response payload:
JsonApiBoom.entityTooLarge([message], [data])
Returns a 413 Request Entity Too Large error where:
message
- optional message.data
- optional additional error data.
JsonApiBoom;
Generates the following response payload:
JsonApiBoom.uriTooLong([message], [data])
Returns a 414 Request-URI Too Large error where:
message
- optional message.data
- optional additional error data.
JsonApiBoom;
Generates the following response payload:
JsonApiBoom.unsupportedMediaType([message], [data])
Returns a 415 Unsupported Media Type error where:
message
- optional message.data
- optional additional error data.
JsonApiBoom;
Generates the following response payload:
JsonApiBoom.rangeNotSatisfiable([message], [data])
Returns a 416 Requested Range Not Satisfiable error where:
message
- optional message.data
- optional additional error data.
JsonApiBoom;
Generates the following response payload:
JsonApiBoom.expectationFailed([message], [data])
Returns a 417 Expectation Failed error where:
message
- optional message.data
- optional additional error data.
JsonApiBoom;
Generates the following response payload:
JsonApiBoom.badData([message], [data])
Returns a 422 Unprocessable Entity error where:
message
- optional message.data
- optional additional error data.
JsonApiBoom;
Generates the following response payload:
JsonApiBoom.locked([message], [data])
Returns a 423 Locked error where:
message
- optional message.data
- optional additional error data.
JsonApiBoom;
Generates the following response payload:
JsonApiBoom.preconditionRequired([message], [data])
Returns a 428 Precondition Required error where:
message
- optional message.data
- optional additional error data.
JsonApiBoom;
Generates the following response payload:
JsonApiBoom.tooManyRequests([message], [data])
Returns a 429 Too Many Requests error where:
message
- optional message.data
- optional additional error data.
JsonApiBoom;
Generates the following response payload:
JsonApiBoom.illegal([message], [data])
Returns a 451 Unavailable For Legal Reasons error where:
message
- optional message.data
- optional additional error data.
JsonApiBoom;
Generates the following response payload:
HTTP 5xx Errors
All 500 errors hide your message from the end user. Your message is recorded in the server log.
JsonApiBoom.badImplementation([message], [data])
Returns a 500 Internal Server Error error where:
message
- optional message.data
- optional additional error data.
JsonApiBoom;
Generates the following response payload:
JsonApiBoom.notImplemented([message], [data])
Returns a 501 Not Implemented error where:
message
- optional message.data
- optional additional error data.
JsonApiBoom;
Generates the following response payload:
JsonApiBoom.badGateway([message], [data])
Returns a 502 Bad Gateway error where:
message
- optional message.data
- optional additional error data.
JsonApiBoom;
Generates the following response payload:
JsonApiBoom.serverUnavailable([message], [data])
Returns a 503 Service Unavailable error where:
message
- optional message.data
- optional additional error data.
JsonApiBoom;
Generates the following response payload:
JsonApiBoom.gatewayTimeout([message], [data])
Returns a 504 Gateway Time-out error where:
message
- optional message.data
- optional additional error data.
JsonApiBoom;
Generates the following response payload: