throw-hydra

HTTP Status Code Handler

An HTTP Error collection to use in your next Hydra REST API.

This is a JSON-LD/Hydra adaptation of https://github.com/kbariotis/throw.js

Installation

npm install throw-hydra.js

Example

var express = require('express');
var app = express();
var throwjs = require('throw.js');
var logger = require('winston');

app.get('/', function (req, res, next) {
  
  next(new throwjs.notFound());
  
});

app.get('/hi', function (req, res, next) {
  
  var options = {
      title: "Oops, nothing to see here.",
      description: "Try another day?",
      next: "/users/",
      prev: req.url         // express can generate the source url for us.
  }
  
  next(new throwjs.notFound(options));
  
});

app.use(function(err, req, res, next) {

    /* 
     The code block below is good-practice for production environment to avoid error traces being revealed to clients, but optional.
        
    if (req.app.get('env') !== 'development' &&
        req.app.get('env') !== 'test') {

        delete err.stack;
    }
    */

    // We catch the error generated by the middleware in this block, we reference err.statusCode[0] as it contains the default RFC compliant error code and is also the default in the absence of a user supplied one.
    res.status(err.statusCode[0] || 500).json(err);

});

var server = app.listen(3000, function () {

  var host = server.address().address;
  var port = server.address().port;

  console.log('Example app listening at http://%s:%s', host, port);

});

Custom Errors

throwjs.customError(options);

Optional Parameters:

• title[optional]: Title error. Defaults to RFC7231 title if non supplied.
• statusCode[optional]: The HTTP Status number to return, multiple status Codes can be provided in addition to the default one. This allows to augment standard HTTP Status Codes (e.g. 403, with a custom, application-specific status code).
• description[optional]: A detailed description of the error to provide the user with more context.
• type[optional]: A JSON-LD/hydra property allowing you to specify the type of this status code (e.g. type = "Error"). See Hydra's documentaiton for more information.
• next[optional]: The next logical place for the user to navigate to. See hydra:next
• previous[optional]: URL leading to this error. See hydra:previous

An example of the options in action could be:

     next(new throwjs.notFound({
      
      title: "Nothing to see here."
      description: "Oops, nothing is at this location, try again later?",
      type: "Error",
      next: "/api/users/",
      previous: "/api/users/non-existant-user"  
         
     }));

Errors

All of the classes below have all parameters set up by default, based on RFC7231. But you can override the message and the errorCode to fit your for personal needs.

400 Bad Request

throwjs.badRequest(options);

401 Unauthorized

throwjs.unauthorized(options);

402 Payment Required

throwjs.paymentRequired(options);

403 Forbidden

throwjs.forbidden(options);

404 Not Found

throwjs.notFound(options);

405 Method Not Allowed

throwjs.methodNotAllowed(options);

406 Not Acceptable

throwjs.notAcceptable(options);

407 Proxy Authentication Required

throwjs.proxyAuthenticationRequired(options);

408 Request Timeout

throwjs.requestTimeout(options);

409 Conflict

throwjs.conflict(options);

410 Gone

throwjs.gone(options);

422 Unprocessable Entity

throwjs.unprocessableEntity(options);

424 Failed Dependency

throwjs.failedDependency(options);

500 Internal Server Error

throwjs.internalServerError(options);

501 Not Implemented

throwjs.notImplemented(options);

502 Bad Gateway

throwjs.badGateway(options);

503 Service Unavailable

throwjs.serviceUnavailable(options);

504 Gateway Timeout

throwjs.gatewayTimeout(options);

505 HTTP Version Not Supported

throwjs.httpVersionNotSupported(options);

511 Network Authentication Required

throwjs.networkAuthenticationRequired(options);

TODO

• Implement more Error Classes