express-api-problem
v2.0.5
Published
A minimal package to assist in returning RESTful exceptions in your APIs
Downloads
168
Maintainers
Readme
express-api-problem
Automatically turns your thrown exceptions to the JSON response while conforming to API problem specification
An express package that lets you handle the API problems with ease. It provides a straightforward implementation of IETF Problem Specification and turns your thrown exceptions to be returned in the below format with the header of content type set to application/problem+json
{
"status": 403,
"type": "http://example.com/problems/out-of-credit",
"title": "You do not have enough credit.",
"detail": "Your current balance is 30, but the item costs 50.",
"instance": "http://example.net/account/12345/logs?id=233"
}
Where
title
is the summary of problemstatus
is the status codedetail
is human readable explanation specific to problemtype
is the absolute URI that identifies the type of probleminstance
is the absolute URI that identifies the specific occurrence of the problem
Installation
yarn add express-api-problem
Usage
Register the middleware
var ApiProblemHandler = require('express-api-problem/middleware');
app.use(ApiProblemHandler);
Throw exceptions while instantiating ApiProblem
having the following signature
var ApiProblem = require('express-api-problem');
// statusCode : HTTP status code to be returned
// title : Title in response
// description : Description of the exception
// additionalDetail : Object having any additional detail that you may want to send
throw new ApiProblem(statusCode, title, description, additionalDetail);
Add the mongoose plugin to automatically transform your model validation errors to API Problem
var mongooseValidator = require('express-api-problem/mongoose-validator');
// Will transform any validation exceptions thrown by your model to
//
// {
// status: 422,
// title: "Validation Failed",
// detail: [
// {
// field: "title",
// message: "Title must be unique"
// },
// {
// field: "expiryDate",
// message: "Expiry Date must be a valid date"
// }
// ]
// }
//
yourSchema.plugin(mongooseValidator);
// Also you can modify the status code and title if required
yourSchema.plugin(mongooseValidator, {
status: 400,
title: "Look before you submit!"
});
// which will result in
// {
// status: 400,
// title: "Look before you submit!",
// detail: [
// {
// field: "title",
// message: "Title must be unique"
// },
// {
// field: "expiryDate",
// message: "Expiry Date must be a valid date"
// }
// ]
// }
Examples
Throwing exception using only status code
throw new ApiProblem(400);
// {
// status: 400,
// title: 'Bad Request',
// type: 'https://www.w3.org/Protocols/rfc2616/rfc2616-sec10.html'
// }
Providing description string
throw new ApiProblem(404, 'User not found', 'No user found against the given ID: 10');
// {
// status: 404,
// title: 'User not found',
// detail: 'No user found against the given ID: 10',
// type: 'https://www.w3.org/Protocols/rfc2616/rfc2616-sec10.html'
// }
Using object in description
throw new ApiProblem(400, 'Validation failed', {
name: 'Name field is required',
email: 'Invalid email given'
});
// {
// status: 422,
// title: 'Unprocessable entity',
// detail: {
// name: ..
// email: ..
// },
// type: 'https://www.w3.org/Protocols/rfc2616/rfc2616-sec10.html'
// }
Adding additional detail to response
throw new ApiProblem(400, 'Insufficient Balance', 'You do not have enough balance to purchase the product', {
available_balance: 'USD 2000',
required_balance: 'USD 12422'
});
// {
// status: 400,
// title: 'Insufficient Balance',
// detail: 'You do not have enough balance to purchase the product',
// available_balance: 'USD 2000',
// required_balance: 'USD 12422',
// type: 'https://www.w3.org/Protocols/rfc2616/rfc2616-sec10.html'
// }
Contributing
Feel free to fork, enhance, create PR and lock issues.
License
MIT © Kamran Ahmed