About HAL and HalBuilder

HAL is a simple way of linking with JSON or XML.

It provides a set of conventions for expressing hyperlinks to, and embeddedness of, related resources - the rest of a HAL document is just plain old JSON or XML.

HAL is a bit like HTML for machines, in that it is generic and designed to drive many different types of application. The difference is that HTML has features for presenting a graphical hypermedia interface to a ‘human actor’, whereas HAL is intended for presenting a machine hypertext interface to ‘automated actors’.

The HAL format, and the HalBuilder Java library provide a consistent approach to both designing and consuming reusable, and navigable REST APIs built on the Java platform.

Installing HalBuilder

HalBuilder is distributed via Maven Central, and the simplest way to get started is to include the halbuilder-standard dependency in your Maven pom.xml:

<dependency>
    <groupId>com.theoryinpractise</groupId>
    <artifactId>halbuilder-standard</artifactId>
    <version>4.0.1</version>
</dependency>

Or declare it in your build.gradle file with:

compile 'com.theoryinpractise:halbuilder-standard:4.0.1'

Getting Started

Usage of the HalBuilder library starts out with an instance of the RepresentationFactory class, this is where you can configure default namespaces and standard links to include on all resource representations, and of course - create or consume representations.

The Representation Factory

RepresentationFactory representationFactory = new StandardRepresentationFactory();

Default Representation URI

The StandardRepresentionFactory class is the entry point to HalBuilder, an instance of this class can be safely reused and injected into the resource classes used by your REST/web framework.

Pretty Printing

By default, all representations are generated in a compact format, but can easily be turned into a pretty printed variation by adding the RepresentationFactory.PRETTY_PRINT URI to a factories flags:

representationFactory.withFlag(RepresentationFactory.PRETTY_PRINT);

Creating Representations

Creating a HAL based resource representation is a simple process of calling newRepresentation from a configured RepresentationFactory. From here it’s a simple matter of using the fluent API to build up your properties, links, and other resource related details.

Representation rep = factory.newRepresentation("/location")
                            .withProperty("name", "Mark Derricutt")
                            .withLink("create", "/api/create");

Rendering Representations

Once you’ve defined your representation instance, you can easily generate the JSON or XML textual representation by calling the toString(contentType) method:

String json = rep.toString(RepresentationFactory.HAL_JSON);

From here it’s just a matter of returning that via whatever web framework you’re using.

Consuming Representations with HalBuilder

Consuming a remote HAL resource representation is as simple as called readRepresentation from an instance of a RepresentionFactory:

RepresentationFactory representationFactory = new DefaultRepresentationFactory();
ReadableRepresentation representation = representationFactory.readRepresentation(...);

Halbuilder by design doesn’t include any built in support for handling HTTP traffic, instead favoring to leave that up to the developer to decide based on requirements and desires ( aka Android or Google App Engine specific libraries ) and simply accepts an InputStream to the readRepresentation method.

From here, using HalBuilder is pretty much the same as it is for constructing representations, albeit in an immutable, or read-only fashion.

The ReadableRepresentation interface provides a simple getLinkByRel method to retrieve a link from the resource. If the link rel doesn’t exist null is returned, and if more than one link is found an exception will be raised, to retrieve 0-N links use the associated getLinksbyRel method.

Using the AsyncHttpClient and the sample [RESTBucks](http://gotohal .net/restbucks/api) API we can do the following:

import com.ning.http.client._
import java.io.InputStreamReader

val client = new AsyncHttpClient()
val response = client.prepareGet("http://gotohal.net/restbucks/api").execute().get()
val representation = rf.readRepresentation(new InputStreamReader(response.getResponseBodyAsStream))
val ordersLinkUrl = representation.getLinkByRel("orders").getHref()

After this code executes, the <code>ordersLinkUrl</code> variable contains:

Representations vs Resources

HAL is all about the representation of REST resources, and not the resources themselves.
// load from the server?
Resources can be navigated by links, relationships identified by the reasons for which we follow a link…​
In addition to merely linking to other resources, the HAL format allows you to actually embed a representation of additional resources directly inside the requested representation.

Contributing to HalBuilder

You can contribute to the HalBuilder project in many ways: discussion on the Google Group, bug reports, feature requests and pull requests on the relevant Github project are also welcone.

Each projects git repository is modeled with the git-flow branching model, so any pull requests should be against the appropriate develop branch.

HalBuilder and its various modules are released under the Apache V2 license.

Building HalBuilder

HalBuilder is distributed via Maven Central as a set of Apache Maven artifacts.

The source for HalBuilder and its modules can be found as separate repositories in the https://github .com/organizations/HalBuilder[HalBuilder Organisation]. Each project is an Apache Maven based project.