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, {
prefix: "/api",
overrideJSON: true,
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) => {
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"
}
}
}
Custom links
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) => {
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) => {
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
)