Hydra-HTTP

HTTP Status Code Handler

Overview

The Problem:

HTTP Status Codes are often sent in a way that is meaningless to the application, much less the end-user.

How Hydra HTTP Solves this:

This library helps you send semantic HTTP Status Codes back to the user, allowing you to populate a status response with a title , description , custom statusCode and a recommended next link for the application/user to continue past the error.

To achieve this, we implement the JSON-LD with Hydra vocabulary to create meaningful HTTP status responses.

The guide and examples below provides a template to begin with.

Installation

    npm install hydra-http --save

The --save tag is optional, this will save the module to your package.json

Example

var express     = require('express');
var app         = express();
var hydra_http  = require('hydra-http');

    app.get('/', function (req, res, next) {
        
        next(new hydra_http.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
        };
        
        next(new hydra_http.NotFound(options));
    });

app.use(function(err, req, res, next) {
    
    /** 
    * 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 () {
  console.log('Example app listening at port 3000');
});

Custom Errors

    hydra_http.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
• id[optional]: Becomes the @id of the JSON-LD payload.

An example of the options in action could be:

     next(new hydra_http.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 title and augment statusCode to fit your for personal needs.

All examples assume:

var hydra_http = require('hydra-http');

400 Bad Request

hydra_http.BadRequest(options);

401 Unauthorized

hydra_http.Unauthorized(options);

402 Payment Required

hydra_http.PaymentRequired(options);

403 Forbidden

hydra_http.Forbidden(options);

404 Not Found

hydra_http.NotFound(options);

405 Method Not Allowed

hydra_http.MethodNotAllowed(options);

406 Not Acceptable

hydra_http.NotAcceptable(options);

407 Proxy Authentication Required

hydra_http.ProxyAuthenticationRequired(options);

408 Request Timeout

hydra_http.RequestTimeout(options);

409 Conflict

hydra_http.Conflict(options);

410 Gone

hydra_http.Gone(options);

422 Unprocessable Entity

hydra_http.UnprocessableEntity(options);

424 Failed Dependency

hydra_http.FailedDependency(options);

500 Internal Server Error

hydra_http.InternalServerError(options);

501 Not Implemented

hydra_http.NotImplemented(options);

502 Bad Gateway

hydra_http.BadGateway(options);

503 Service Unavailable

hydra_http.ServiceUnavailable(options);

504 Gateway Timeout

hydra_http.GatewayTimeout(options);

505 HTTP Version Not Supported

hydra_http.HttpVersionNotSupported(options);

511 Network Authentication Required

hydra_http.NetworkAuthenticationRequired(options);

TODO

• Implement more Error Classes
• Option to override the statusCode (e.g. replace a 401 with 40001), rather than simply augment it (e.g. currently providing a statusCode paramater adds another statusCode to the array e.g. [401,400001]).

Acknowledgements

This is a JSON-LD/Hydra adaptation of Throw.js