hyper-json

![Build
Status](http://travis-ci.org/cainus/hyper-json)


This is a fluent interface for adding links to json documents. Links are added in the Hyper+json style (documented
here ).

This sort of library is useful if you want to create hypermedia apis using json.

A few examples:

$3

Creates json strings from objects.
``javascript
var hyperjson = require('hyperjson');
hyperjson({thisis : "a test"}).toString(); // '{"thisis":"a test"}'
`

$3

Returns the resulting "json" object.
`javascript
hyperjson({thisis : "a test"}).toObject(); // {"thisis":"a test"}
`

$3

Adds a property to the json output.
`javascript
hyperjson({thisis : "a test"})
.property("prop1", {random : "value"})
.toObject(); /* {
thisis : "a test",
prop1 : {
random : "value"}
}
*/
`

$3

Adds a link to the json output.
`javascript
hyperjson({thisis : "a test"})
.link("self", "http://localhost:8080/api/test")
.toObject(); /* {
thisis : "a test",
_links : {
self : {
href : "http://localhost:8080/api/test"
}
}
*/
`
This can be called multiple times to add more links. Note that if two links are assigned to the same key, the key will be mapped to an array of links.
`javascript
hyperjson({thisis : "a test"})
.link("self", "http://localhost:8080/api/test")
.link("parent", "http://localhost:8080/api/")
.link("kid", "http://localhost:8080/api/kid1")
.link("kid", "http://localhost:8080/api/kid2")
.toObject(); /* {
thisis : "a test",
_links : {
self : {
href : "http://localhost:8080/api/test"
},
parent : {
href : "http://localhost:8080/api/"
},
kid : [{
href : "http://localhost:8080/api/kid1"
},{
href : "http://localhost:8080/api/kid2"
}]
}
*/
`
link() can also be used to add non-traditional links for HTTP methods other than GET.
`javascript
hyperjson({thisis : "a test"})
.link("self", "http://percolatorjs.com", {type : 'application/json', schema : {}, method : 'POST'})
.toObject(); /* {
thisis : "a test",
_links : {
self : { href : "http://percolatorjs.com",
type : 'application/json',
schema : {},
method : 'POST' }
}
}
*/
`
In addition, the options argument of link() can also take a when property, which maps to a function or an expression. The link will be added if and only if this function or expression is truthy.
`javascript
hyperjson({thisis : "a test"})
.link("self", "http://percolatorjs.com", {when: 1 + 1 === 2, method: 'POST'})
.toObject(); /* {
thisis : "a test",
_links : {
self : {
href : "http://percolatorjs.com",
method: 'POST'
}
}
}
*/

hyperjson({thisis : "a test"})
.link("self", "http://percolatorjs.com", {when: function(obj) {obj.thisis === "a test"})
.toObject(); /* {
thisis : "a test",
_links : {
self : { href : "http://percolatorjs.com" }
}
}
*/

hyperjson({thisis : "a test"})
.link("self", "http://percolatorjs.com", {when: function(obj) {obj.thisis === "not a test"})
.toObject(); // { thisis : "a test" } - no links are created

``
Check out the hyper+json spec if you want to read more about these kinds of links.