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’.
Taken from the HAL Specification
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.
HalBuilder is distributed via Maven Central, and the simplest way to get started is to include the
halbuilder-standard dependency in your Maven
<dependency> <groupId>com.theoryinpractise</groupId> <artifactId>halbuilder-standard</artifactId> <version>4.0.1</version> </dependency>
Or declare it in your
build.gradle file with:
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.
RepresentationFactory representationFactory = new StandardRepresentationFactory();
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.
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");
Once you’ve defined your representation instance, you can easily generate the JSON or XML textual representation by calling the
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 a remote HAL resource representation is as simple as called
readRepresentation from an
instance of a
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
From here, using HalBuilder is pretty much the same as it is for constructing representations, albeit in an immutable, or read-only fashion.
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
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:
|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…|
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
HalBuilder and its various modules are released under the Apache V2 license.