halo

An AngularJS service for handling RESTful communication with HAL


Install
bower install halo

Documentation

Note: this is a rapidly changing project still in early development. It is still missing significant functionality.

HALo

HALo (also written as Halo) is an AngularJS module designed to make it easier to communicate with RESTful web services employing HAL (Hypertext Application Language) from your Angular application.

Halo treats almost every API response as a resource. Interaction with a resource takes place over HTTP. Every resource has access to methods corresponding to HTTP request methods such as GET and POST.

Halo assumes that your API conforms to the "hypermedia as the engine of application state" (commonly written as HATEOAS) constraint of RESTful services. That is, it expects a single entry point to return a resource containing links to other available resources identified by well-documented media types.

Halo does not provide a mechanism for creating "models" in the sense that you don't need to tell it which properties and methods individual resources should have. That information is discovered through the API and should be documented by your API provider.

Installation

Halo is available through Bower so you can install it with bower install halo. Alternatively, download the minified dist/halo.min.js (for production) or lib/halo.js (for development) file from GitHub manually.

Then you'll need to update your main Angular module definition to add the halo module as a dependency:

var yourApp = angular.module("yourApp", [
    "halo",
    // ... any other dependencies
]);

Usage

Halo provides a service that allows you to interact with a discoverable REST API. The idea is that you give it a root URL to which a GET request returns a root resource describing possible routes to navigate through the API. The service consists of a single constructor function. Inject the service and call the static get method to retrieve the root resource:

yourApp.controller(function (Halo) {
    Halo.get().then(function (response) {
        var rootResource = response.resource;
    });
});

Every call into the API returns a promise. The promise will be fulfilled with an object with several properties:

  • resource is an instance of a resource
  • status is the HTTP status code of the response
  • data is the raw HTTP response content (deserialised to a JavaScript object)
  • headers is a getter function that will return the value of HTTP response headers

Resources

Every request returns a resource instance. Each instance can have some useful properties:

  • links is a map of link relation types to Link objects. More on Link objects below
  • embedded is a map of link relation types to embedded Resource objects
  • All other properties are data specific to the resource instance

As well as those properties resource objects have access to a method for each allowed HTTP method. These methods are useful for communicating with a resource itself, via its self link.

  • The get, delete, options and head methods all take a single config argument and make the respective request to the resource's "self" link

  • The post method takes an object representing a new resource as the first argument and a config object as the second argument, and makes a POST request to the "self" link with the new resource object in the body

  • The put method takes a single config object argument and makes a PUT request to the "self" link with the resource's instance properties in the body

Links

Many resources will have a links property. Links provide routes through an API. Inspecting the links object will allow your application to determine available actions. Link objects are very simple. They have a couple of properties:

  • rel is the link relation type. Often this will be a URL to a web page at which documentation for the relation type can be found
  • href is the URL at which a resource can be found

As well as those properties link objects have access to a method for each allowed HTTP method.

Configuration

The Halo service can be configured via its provider. You can inject the provider into a config function. The following configuration methods are available:

  • setRoot({string}) sets the URL that will be requested as the API entry point, defaulting to "/"
  • setMethods({Array}) sets the allowed HTTP methods as an array of strings, defaulting to ["GET", "PUT", "POST", "PATCH", "DELETE", "OPTIONS"]

Example

angular.module("demoApp", [
    "halo"
]).config(function (HaloProvider) {
    HaloProvider.setRoot("/api");
});

Examples

Assume all of the following examples appear in an appropriate location within an Angular application (such as a controller function).

Get the root resource then a child of it

Halo.get()
    .then(function (response) {
        var links = response.resource.links; // Get links from root resource
        return links.customers.get(); // GET request to "customers" resource
    })
    .then(function (response) {
        var Customer = response.resource; // Get the Customer resource instance
    })

Manipulating a single resource from a collection

Halo.get()
    .then(function (response) {
        var links = response.resource.links; // Get links from root resource
        return links.customers.get(); // GET request to "customers" resource
    })
    .then(function (response) {
        // If the customers resource returns a collection its elements will be
        // available as links
        var customers = response.resource.links;
        return customers[0].get();
    })
    .then(function (response) {
        var customer = response.resource; // Get the single customer resource
        customer.name = "Bill"; // Modify the resource
        customer.put(); // PUT the changes to the server
    })

Creating a new resource

Halo.get()
    .then(function (response) {
        var links = response.resource.links; // Get links from root resource
        return links.customers.get(); // GET request to "customers" resource
    })
    .then(function (response) {
        var Customers = response.resource; // Get the "customers" resource
        return Customers.post({    // Create and save a new "customer" resource
            name: "James"
        });
    })
    .then(function (response) {
        // New resource was created successfully
    })

Caching references to resources

This example assumes you want to remove the need to request the root resource every time you need access to a child resource. Module-wide storage is easily achieved in Angular through services:

angular
    .module("demoApp", [])
    .factory("API", function () {
        return {};
    })
    .run(function (Halo, API) {
        Halo.get().then(function (response) {
            API.Root = response.resource; // Save the root resource
        });
    })
    .controller("demoCtrl", function (API) {
        // Use the "cache" service instead of Halo itself
        // You could cache the "customer" resource too at this point
        API.Root.links.customers.get();
    })