rjh

restify-json-hal

extends restify with JSON HAL

Showing:

Popularity

Downloads/wk

6

GitHub Stars

3

Maintenance

Last Commit

5yrs ago

Contributors

2

Package

Dependencies

1

License

Apache-2.0

Type Definitions

Tree-Shakeable

No?

Categories

Readme

restify-json-hal

Extends Restify with the application/hal+json formatter following the JSON HAL and URI Templates spec.

This way you easily add the basics of HATEOAS to your API and brings it that much closer to the Glory of REST.

howto

var restify = require('restify');
var restifyJSONHAL = require("restify-json-hal");

var server = restify.createServer();

server.use(restifyJSONHAL(server));

server.get('/', (request,response,next) => {
  response.send({msg: "root"});
  return next();
});

server.get('/echo', (request,response,next) => {
  response.send({msg: "echo"});
  return next();
});

server.get('/echo/:name', (request,response,next) => {
  response.send(request.params);
  return next();
});

server.listen(8080, function () {
  console.log('%s listening at %s', server.name, server.url);
});

A call to / renders:

(remember to have the accept: application/hal+json header)

{
  "msg": "root",
  "_links": [
    {
      "href": "/",
      "rel": "self",
      "method": "GET"
    },
    {
      "href": "/echo",
      "rel": "getecho",
      "method": "GET"
    }
  ]
}

A call to /echo renders

{
  "msg": "echo",
  "_links": [
    {
      "href": "/echo",
      "rel": "self",
      "method": "GET"
    },
    {
      "templated": true,
      "href": "/echo/{name}",
      "rel": "getechoname",
      "method": "GET"
    }
  ]
}

A call to /echo/juravenator renders

{
  "name": "juravenator",
  "_links": [
    {
      "href": "/echo/juravenator",
      "rel": "self",
      "method": "GET"
    }
  ]
}

extra parameters and options

var restify = require('restify');
var restifyJSONHAL = require("restify-json-hal");

var server = restify.createServer();
server.use(restify.queryParser());

server.use(restifyJSONHAL(server, {
  // add a prefix to every link
  // usefull when url rewriting happens along the way
  prefix: "/api",
  // this overrides the formatter for application/json to also
  // include JSON HAL data
  overrideJSON: true,
  // makes "_links" an object instead of an array
  makeObjects: true
}));

server.get('/', (request,response,next) => {
  response.send({msg: "root"});
  return next();
});

server.get('/echo', (request,response,next) => {
  response.send({msg: "echo"});
  return next();
});

server.get('/hello', (request,response,next) => {
  /**
   * HAL: This call does some stuff
   * @name customName
   * @param name
   * @deprecated
   * @alias get-hello
   */
   var name = request.params.name || "World";
   var msg = `Hello, ${name}`;
   response.send({msg: msg});
   return next();
});

server.get('/echo/:name', (request,response,next) => {
  response.send(request.params);
  return next();
});

server.listen(8080, function () {
  console.log('%s listening at %s', server.name, server.url);
});

Now, calling / with header accept: application/json will render

{
  "msg": "root",
  "_links": {
    "self": {
      "href": "/api",
      "method": "GET"
    },
    "getecho": {
      "href": "/api/echo",
      "method": "GET"
    },
    "customName": {
      "href": "/api/hello{?name}",
      "deprecation": true,
      "title": "get-hello",
      "description": "This call does some stuff",
      "templated": true,
      "method": "GET"
    }
  }
}

restify-json-hal exposes the addLink function that allows you to link to another resource that would normally not be considered related.

An example:

server.get('/books/:bookname', (request,response,next) => {
  /**
   * HAL: Gets book and author
   * @name getauthor
   */
  var author = "alan-watts";
  response.addLink("get", `/authors/${author}`);
  response.send({
    title: request.params.bookname,
    author: author
  });
  return next();
});

server.get('/authors/:authorname', (request, response, next) => {
  /**
   * HAL: Gets author and published books
   * @name getauthor
   */
  var books = ["the-way-of-zen"];
  for (var i = 0; i < books.length; i++) {
    response.addLink("get", `/books/${books[i]}`, books[i]);
  }
  response.send({
    author: request.params.authorname,
    books: books
  });
});

A call to /books/the-way-of-zen will render:

{
  "title": "the-way-of-zen",
  "author": "alan-watts",
  "_links": [
    {
      "href": "/books/the-way-of-zen",
      "rel": "self",
      "description": "Gets book and author",
      "method": "GET"
    },
    {
      "rel": "getauthor",
      "method": "GET",
      "description": "Gets author and published books",
      "href": "/authors/alan-watts"
    }
  ]
}

A call to /authors/alan-watts will render:

{
  "author": "alan-watts",
  "books": [
    "the-way-of-zen"
  ],
  "_links": [
    {
      "href": "/authors/alan-watts",
      "rel": "self",
      "description": "Gets author and published books",
      "method": "GET"
    },
    {
      "rel": "the-way-of-zen",
      "method": "GET",
      "description": "Gets book and author",
      "href": "/books/the-way-of-zen"
    }
  ]
}

todo

  • _embedded, somehow
  • figure out how to use profile properly
  • CURIE syntax
  • how to document parameters? (probably related to profile)

Rate & Review

Great Documentation0
Easy to Use0
Performant0
Highly Customizable0
Bleeding Edge0
Responsive Maintainers0
Poor Documentation0
Hard to Use0
Slow0
Buggy0
Abandoned0
Unwelcoming Community0
100
No reviews found
Be the first to rate

Alternatives

No alternatives found

Tutorials

No tutorials found
Add a tutorial