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:
-
resourceis an instance of a resource -
statusis the HTTP status code of the response -
datais the raw HTTP response content (deserialised to a JavaScript object) -
headersis 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:
-
linksis a map of link relation types to Link objects. More on Link objects below -
embeddedis 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,optionsandheadmethods all take a singleconfigargument and make the respective request to the resource's "self" linkThe
postmethod 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 bodyThe
putmethod 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:
-
relis the link relation type. Often this will be a URL to a web page at which documentation for the relation type can be found -
hrefis 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();
})