Halberd
HAL is a hypermedia-aware serialization format, which can be represented using JSON and XML format. You can find more details about HAL in specification draft.
It's obviously particularly useful for RESTful API delivering real Hypermedia contents (cf HATEOAS).
naholyr/js-hal
Differences from- It's meant to also be used on the client side. In other words, it accepts a full hal+json (with links) on the
hal.Resource
constructor. - Support for requirejs/AMD.
- [planned] Accept embedded resources on the
hal.Resource
constructor.
Usage
In your browser
Compatibility
Don't know, didn't test. It may not even work on the browser, who knows ?
OK, more seriously you'll require:
JSON.stringify
Array.prototype.forEach
Array.prototype.reduce
Object.prototype.hasOwnProperty
In Node.JS
npm install halberd
var hal = ; var resource = name: "Harry" '/harry';resourcelink'hello' '/harry/hello';console;
API
Resource(object, uri)
This class designs a HAL resource:
object
are the base fields of this resource- Note that you can define
_links
and_embedded
properties, this is at your own risks - If you set
href
property anduri
is undefined, it will be used instead ofuri
and deleted uri
is the link to this property (as<link rel="self">
)
Link(rel, href)
or Link(rel, attributes)
This class designs a HAL link:
rel
is mandatoryhref
orattributes.href
is mandatory
Resource#link(link)
or Resource#link(rel, href)
or Resource#link(rel, attributes)
Adds a new link to resource.
Resource#embed(rel, resource[s])
Embeds other resource(s) to current resource.
Resource#links()
Returns all links of a resource.
Resource#links(rel)
or Resource#links(relsArray)
Returns links of a given relation (or relations) of a resource.
Resource#link(rel)
Returns the first link of a given relation of a resource, or null if there is no such link.
Resource#toXML()
Returns XML representation.
Note: embedded resources rel
will be naively singularized by removing last 's'. See Resource#toJSON
for more information.
Resource#toJSON()
Returns JSON representation.
Note: rel
will be naively pluralized by appending a 's' if there is not. This is due to differences between JSON and XML representation on embedded relationship and rel
attribute.
Example
// A resourcevar ordersCollection = currentlyProcessing: 14 shippedToday: 20 "/orders"; // LinksordersCollectionlink"next" "/orders?page=2";ordersCollectionlink"find" href: "/orders{?id}" templated: true; // Another resourcevar order123 = total: 3000 currency: "USD" status: "shipped" "/orders/123";// Alternative ways to linkorder123link"basket" "/baskets/98712";order123link"customer" href: "/customers/7809"; // Yet another resourcevar order124 = total: 2000 currency: "USD" status: "processing" "/orders/124";order124link"basket" "/baskets/97213";order124link"customer" "/customers/12369"; // Embed the resourcesordersCollection;
Calling ordersCollection.toJSON(' ')
:
"currentlyProcessing": 14 "shippedToday": 20 "_links": "self": "href": "/orders" "next": "href": "/orders?page=2" "find": "href": "/orders{?id}" "templated": "true" "_embedded": "orders": "total": 30 "currency": "USD" "status": "shipped" "_links": "self": "href": "/orders/123" "basket": "href": "/baskets/98712" "customer": "href": "/customers/7809" "total": 20 "currency": "USD" "status": "processing" "_links": "self": "href": "/orders/124" "basket": "href": "/baskets/97213" "customer": "href": "/customers/12369"
Calling ordersCollection.toXML(' ')
:
14 20 30 USD shipped 20 USD processing
Yes, JSON seems a lot more verbose, but it's because of the spaces. In production you won't add indentation and then JSON is 517 bytes long, versus 625 bytes of XML.
Not yet, XML, not yet.