Links

By far, the most important element in the HAL format is the way it standardizes Links in JSON. Here’s what a link looks like in a HAL document:

"_links": {
  "self": { "href": "/orders" },
  "next": { "href": "/orders?page=2" },
  "find": { "href": "/orders{?id}", "templated": true } 
},

Note that each link object has an identifier (self, next, find). This is required for HAL documents. It is the identifier that the client application will store in code, not the actual URL value. The URLs appear in the href property and these URLs may actually be URL templates (see ). HAL leverages the URI Template specification (RFC6570) and the templated:"true" property for these.

In HAL, all link objects appear as part of a "_links" collection. These collections can appear in several places within a single HAL document.

Objects and Properties

HAL also supports passing plain JSON objects and name–value pairs. These typically appear as a collection of properties at the root of a HAL document. For example, the Amazon API Gateway service emits HAL responses. Following are a couple of examples of the 26 resource models the AWS Gateway API produces:

{
  "domainName" : "String",
  "certificateName" : "String",
  "certificateUploadDate" : "Timestamp",
  "distributionDomainName" : "String"
}

{
  "id" : "String",
  "description" : "String",
  "createdDate" : "Timestamp",
  "apiSummary" : {
    "String" : {
      "String" : {
        "authorizationType" : "String",
        "apiKeyRequired" : "Boolean"
      }
    }
  }
}

As we discussed in Chapter 2, JSON Clients, tracking domain objects is an important aspect of API clients. By design, the HAL format does not offer any additional design elements to make this any different than working with plain JSON responses. So HAL clients will need to know all the possible objects and models the API will be emitting before that client app can interact with the API.

Embedded Links and Objects

Finally, the HAL design allows for additional resources (and their associated links and properties) to appear as embedded models within responses. This makes it possible to return a single HAL document that includes multiple server-side resources. This acts as a way to reduce the number of HTTP requests and improves the perceived responsiveness of the service.

Following is a more extensive HAL document that includes all the features we’ve covered so far:

{
  "_links": {
    "self": { "href": "/orders" },
    "curies": [{ "name":"ea", "href":"http://example.com/docs/rels/{rel}", 
      "templated": true }],
    "next": { "href": "/orders?page=2" },
    "ea:find": {
      "href": "/orders{?id}",
      "templated": true
    },
    "ea:admin": [{
      "href": "/admins/2",
      "title": "Fred"
    }, {
      "href": "/admins/5",
      "title": "Kate"
    }]
  },
  "currentlyProcessing": 14,
  "shippedToday": 20,
  "_embedded": {
    "ea:order": [{
      "_links": {
        "self": { "href": "/orders/123" },
        "ea:basket": { "href": "/baskets/98712" },
        "ea:customer": { "href": "/customers/7809" }
      },
      "total": 30.00,
      "currency": "USD",
      "status": "shipped"
    }, {
      "_links": {
        "self": { "href": "/orders/124" },
        "ea:basket": { "href": "/baskets/97213" },
        "ea:customer": { "href": "/customers/12369" }
      },
      "total": 20.00,
      "currency": "USD",
      "status": "processing"
    }]
  }
}

The preceding example also shows HAL’s curies support (). HAL uses the W3C Compact URI Syntax (CURIES) as a way to shorten long unique link identifiers. This is an optional HAL element but one that you may encounter “in the wild.”

Quick Summary

So the HAL hypermedia format focuses on making it possible for services to change URLs at runtime without breaking client applications. It does this by formalizing the way URLs are expressed in responses using the HAL Link element (e.g., "_links:{"self":{"href":"/home/"}}). HAL also supports passing state data in plain JSON properties or objects and provides the ability to nest Resources using the "_embedded":{…} element.

That gives us enough information to add HAL support for our TPS web API. First we’ll modify the TPS API to emit HAL-compliant responses. Then we’ll build a general HAL client that reads those responses.

Links

The getLinks routine searches through the runtime internal WeSTL document and composes the appropriate link elements for the response. It looks like this:

// emit _links object
function getLinks(wstlObject, root, segment, relRoot) {
  var coll, items, links, i, x;

  links = {};

  // list-level actions
  if(wstlObject.actions) { 
    coll = wstlObject.actions;
    for(i=0,x=coll.length;i<x;i++) {
      links = getLink(links, coll[i], relRoot);
    }

    // list-level objects
    if(wstlObject.data) { 
      coll = wstlObject.data;
      items = [];
      for(i=0,x=coll.length;i<x;i++) {
        item = {};
        link = getItemLink(wstlObject.actions);
        if(link.href) {
          item.href = link.href.replace(/{key}/g, coll[i].id)||"#";
        }
        item.title = coll[i].title||coll[i].nick;
        items.push(item);
      }
      links[checkRel(segment, relRoot)] = items; 
    }
  }
}

There are just a few interesting elements to the getLinks routine:

If there are actions in the WeSTL document, compose them as valid HAL links (that’s the getLink routine) and add them to the document.

If there is data associated with the response, walk through all the objects and resolve any direct item link data and add it to the document.

Finally, check each of the links (with the checkRel routine) to see if it’s a registered IANA link relation value or an application-specific link identifier.

That last step makes sure to follow the rules for link relations (from RFC5988) and include a fully qualified domain name (FQDN) to the link’s rel value for any identifiers that are not already registered.

Properties

The next step is to emit any HAL properties in the response. Our TPS API could emit some plain HTML (via the internal content element). It may also have some related data objects (via the internal related object collection) to help support drop-down lists or other rendering. We also need to emit root-level HAL properties if the response has just one associated data object. This is not a requirement of HAL—it just makes emitting compliant HAL documents easy for our representor.

The code that handles the content and related elements appears in the haljson routine (refer back to Example 4-2). The code that emits the data object as properties (getProperties) looks like this:

// emit root properties
function getProperties(hal, wstlObject) {
  var props;

  if(wstlObject.data && wstlObject.data[0]) { 
    props = wstlObject.data[0]; 
    for(var p in props) {
      hal[p] = props[p]; 
    }
  }
  return hal;
}

The getProperties routine does the following:

If there is only one data object in the resource collection…

Get an index collection of that object’s property names.

Add each property name–value pair to the HAL document.

Embedded

The last step in supporting valid HAL responses is dealing with the optional _embedded section. This element of the HAL design is meant to optimize long lists of HAL link elements by including the associated objects in the response. This is a kind of internal caching helper. For our HAL representor, we will generate an _embedded section (using the getEmbedded function) whenever the resource behind the HAL response has multiple objects in the internal WeSTL data collection.

The code looks like this:

// emit embedded content
function getEmbedded(wstlObject, root, segment, relRoot) {
  var coll, items, links, i, x;

  links = {};

  // list-level objects
  if(wstlObject.data) {
    coll = wstlObject.data;
    items = [];
    for(i=0,x=coll.length;i<x;i++) { 
      item = {};
      link = getItemLink(wstlObject.actions); 
      if(link.href) {
        item.href = link.href.replace(/{key}/g, coll[i].id)||"#"; 
      }
      for(var p in coll[i]) {
        item[p] = coll[i][p]; 
      }
      items.push(item); 
    }
    links[checkRel(segment, relRoot)] = items;
  }

  return links; 
}

There are a number of things going on here. After grabbing the collection of resource data objects, the getEmbedded routine does the following:

Walk through the object collection to create an embedded item object.

Pull that item’s direct link (using the getItemLink function).

Resolve the direct link (if there is a URI Template).

Populate the embedded item with the internal object’s properties.

Add the completed item to the embedded collection.

Finally, after checking the item link for RFC5988 compliance, return the _embedded collection for inclusion in the HAL document.

There are a couple of internal routines not shown here. They handle finding the data object’s direct link template (getItemLink), creating valid HAL links (getLink), and RFC5988 compliance (checkRel). You can check the source code for details behind these.

Sample TPS Output from the HAL Representor

With the HAL representor completed, the TPS web API now emits proper HAL representations. Example 4-3 shows the output from the TPS server for the Home resource.

{
  "_links": {
    "self": {
      "href": "http://rwcbook06.herokuapp.com/home/",
      "title": "Home",
      "templated": false,
      "target": "app menu hal"
    },
    "http://rwcbook06.herokuapp.com/files/hal-home-task": {
      "href": "http://rwcbook06.herokuapp.com/task/",
      "title": "Tasks",
      "templated": false,
      "target": "app menu hal"
    },
    "http://rwcbook06.herokuapp.com/files/hal-home-user": {
      "href": "http://rwcbook06.herokuapp.com/user/",
      "title": "Users",
      "templated": false,
      "target": "app menu hal"
    },
    "http://rwcbook06.herokuapp.com/files/hal-home-home": []
  },
  "content": "<div class="ui segment"><h3>Welcome to TPS at BigCo!</h3> _
  <p><b>Select one of the links above.</b></p></div>",
  "related": {},
  "_embedded": {
    "http://rwcbook06.herokuapp.com/files/hal-home-home": []
  }
}

And Example 4-4 shows the HAL output for a single TPS Task object.

{
  "_links": {
    "http://rwcbook06.herokuapp.com/files/hal-task-home": {
      "href": "http://rwcbook06.herokuapp.com/home/",
      "title": "Home",
      "templated": false,
      "target": "app menu hal"
    },
    "self": {
      "href": "http://rwcbook06.herokuapp.com/task/",
      "title": "Tasks",
      "templated": false,
      "target": "app menu hal"
    },
    "http://rwcbook06.herokuapp.com/files/hal-task-user": {
      "href": "http://rwcbook06.herokuapp.com/user/",
      "title": "Users",
      "templated": false,
      "target": "app menu hal"
    },
    "http://rwcbook06.herokuapp.com/files/hal-task-item": {
      "href": "http://rwcbook06.herokuapp.com/task/{key}",
      "title": "Detail",
      "templated": true,
      "target": "item hal"
    },
    "http://rwcbook06.herokuapp.com/files/hal-task-edit": {
      "href": "http://rwcbook06.herokuapp.com/task/{key}",
      "title": "Edit Task",
      "templated": true,
      "target": "item edit hal"
    },
    "http://rwcbook06.herokuapp.com/files/hal-task-remove": {
      "href": "http://rwcbook06.herokuapp.com/task/{key}",
      "title": "Remove Task",
      "templated": true,
      "target": "item edit hal"
    },
    "http://rwcbook06.herokuapp.com/files/hal-task-markcompleted": {
      "href": "http://rwcbook06.herokuapp.com/task/completed/{id}",
      "title": "Mark Completed",
      "templated": true,
      "target": "item completed edit post form hal"
    },
    "http://rwcbook06.herokuapp.com/files/hal-task-assignuser": {
      "href": "http://rwcbook06.herokuapp.com/task/assign/{id}",
      "title": "Assign User",
      "templated": true,
      "target": "item assign edit post form hal"
    },
    "http://rwcbook06.herokuapp.com/files/hal-task-task": [
      {
        "href": "//rwcbook06.herokuapp.com/task/1m80s2qgsv5",
        "title": "Run client-side tests"
      }
    ]
  },
  "id": "1m80s2qgsv5",
  "title": "Run client-side tests",
  "tags": "test",
  "completeFlag": "false",
  "assignedUser": "alice",
  "dateCreated": "2016-01-28T07:14:07.775Z",
  "dateUpdated": "2016-01-31T16:49:47.792Z"
}

Note that the output includes link objects marked with the target property. This is not a defined HAL property. Our TPS server emits this property to help the HAL client know how to handle the link—whether it should be rendered at the top of every page ("app"), just for object lists ("list"), or only when there is a single object to display ("item"). We’ll cover more of that in the next section of this chapter.

The HTML Container

Like all single-page apps (SPAs), this one starts with a single HTML document acting as the container for all the client–server interactions. Our HAL client container looks like this:

<!DOCTYPE html>
<html>
  <head>
    <title>HAL</title>
    <link href="./semantic.min.css" rel="stylesheet" />
    <style>#dump {display:none;}</style>
  </head>
  <body>
    <div id="toplinks"></div> 
    <h1 id="title" class="ui page header"></h1>
    <div id="content"></div>
    <div id="links"></div>
    <div class="ui two column grid" style="margin-top: 2em">
      <div class="column">
        <div id="embedded" class="ui segments"></div>
        <div id="properties"></div>
      </div>
      <div class="column">
        <div id="form"></div>
      </div>
    </div>
    <div>
      <pre id="dump"></pre>
    </div>
  </body>
  <script src="uritemplate.js">//na</script>  
  <script src="dom-help.js">//na</script>
  <script src="hal-client.js">//na </script>
  <script>
    window.onload = function() {
      var pg = hal();
      pg.init("/home/", "TPS - Task Processing System"); 
    }
  </script>
</html>

Most of the content should look familiar. Our HTML layout for the app (starting at ) is a bit more involved than in previous apps in order to accommodate the HAL elements (links, properties, embedded) but the rest is similar to our JSON client app. Note that there are three scripts for this client (). The familiar dom-help.js file, the expected hal-client.js library and a new JS module: uritemplate.js. The HAL design relies upon RFC5988 (URI Template) compliant links so we’ll use a standard library to handle these.

Finally, at , the initial URL is supplied and the hal-client.js library is kicked off. We’ll spend the rest of our walk-through in the hal-client.js file.

The Top-Level Parse Loop

After making the initial HTTP request, the response is passed to the parseHAL routine. Like all our SPA apps, the HAL client relies on a simple request, parse, render loop. Here’s the top-level parse loop for this app.

  // primary loop
  function parseHAL() {
    halClear();
    title();
    setContext(); 
    if(g.context!=="") { 
      selectLinks("app", "toplinks");
      selectLinks("list", "links");
      content();
      embedded();
      properties();
    }
    else {
      alert("Unknown Context, can't continue"); 
    }
  }

After clearing the user interface of any previously rendered content and setting the title, the web client kicks off a set of HAL-specific routines. Here are the highlights:

First, the setContext routine determines which Object is being returned (Home, Task, or User).

If we have a valid context, the HAL-specific elements are parsed and rendered (including filtering the link pile for display in the proper locations).

Finally, if the service returned a context the client is not prepared to deal with, an alert is displayed.

Note that we’re hardcoding the Object knowledge into this app (via setContext). We are also expecting special information from the service about each link object to know how and where to display it. We’ll see more on that in the next section.

Links

HAL’s strength is the ability to return well-identified link objects for API clients. For our client, the selectLinks routine parses the HAL _links collection and determines how to build and render the link information in the proper place on the screen.

Here’s the code:

// select and render HAL links
function selectLinks(filter, section, itm) { 
  var elm, coll;
  var menu, item, a, sel, opt, id;

  elm = d.find(section);
  d.clear(elm);
  if(g.hal._links) { 
    coll = g.hal._links;
    menu = d.node("div");
    menu.className = "ui blue menu";

    for(var link in coll) {
      if(coll[link].target && coll[link].target.indexOf(filter)!==-1) { 
        id = (itm && itm.id?itm.id:"");

        a = d.anchor({ 
          rel:link,
          href:coll[link].href.replace('{key}',id),
          title:(coll[link].title||coll[link].href.replace('{key}',id)),
          text:(coll[link].title||coll[link].href.replace('{key}',id))
        });

        // add internal attributes 
        a.setAttribute("templated", coll[link].templated||"false");
        a = halAttributes(a,coll[link]);

        item = d.node("li");
        item.onclick = halLink; 
        item.className = "item";

        d.push(a, item);
        d.push(item, menu);
      }
    }
    d.push(menu, elm); 
  }
}

There is a lot going on in this routine. That’s because most of the information in a HAL response is stored in the _links collection. Let’s do the walk-through…

First (at ) the signature of the selectLinks function takes up to three values: The string (filter) to use against the our custom link.target field, the name of the HTML DOM element (section) where we’ll render the links, and (optionally) the current data object (itm) to use when resolving item-level links. We’ll see this last argument in use when we scan the code for handling HAL’s _embedded collection.

After making sure this response actually has links () and filtering the collection to match our needs (), the code builds up an HTML <a>…</a> element (), adds some local attributes the code uses to handle user clicks at runtime, marks the link if it is using a URL template (), and then (at ) attaches a local click event (halLink) that can sort out just how to handle the requested action. Finally, () the resulting links are added to the HTML DOM and rendered on the screen.

Figure 4-2 shows how the elements in the HAL _links collection is rendered on the screen for the list of Task objects.

Figure 4-2. Rendering HAL _links for task objects

Embedded

HAL’s _link collection doesn’t just contain a list of action links (like the ones rendered before). The HAL response may also contain one or more links to associated resources. For example, the TPS web API returns a list of Task objects as link elements in a HAL response. The same response also includes the associated Task objects in the _embedded section:

{
  "_links": {
    "self": {
      "href": "http://rwcbook06.herokuapp.com/task/",
      "title": "Tasks",
      "templated": false,
      "target": "app menu hal"
    },
    "http://rwcbook06.herokuapp.com/files/hal-task-task": [
      {
        "href": "//rwcbook06.herokuapp.com/task/1m80s2qgsv5",
        "title": "Run client-side tests"
      },
      {
        "href": "//rwcbook06.herokuapp.com/task/1sog9t9g1ob",
        "title": "Run server-side tests"
      },
      {
        "href": "//rwcbook06.herokuapp.com/task/1xya56y8ak1",
        "title": "Validate client-side code changes"
      }
    ]
  },
  "_embedded": {
    "http://rwcbook06.herokuapp.com/files/hal-task-task": [
      {
        "href": "//rwcbook06.herokuapp.com/task/1m80s2qgsv5",
        "id": "1m80s2qgsv5",
        "title": "Run client-side tests",
        "tags": "test",
        "completeFlag": "false",
        "assignedUser": "alice",
        "dateCreated": "2016-01-28T07:14:07.775Z",
        "dateUpdated": "2016-01-31T16:49:47.792Z"
      },
      {
        "href": "//rwcbook06.herokuapp.com/task/1sog9t9g1ob",
        "id": "1sog9t9g1ob",
        "title": "Run server-side tests",
        "tags": "test",
        "completeFlag": "false",
        "assignedUser": "",
        "dateCreated": "2016-01-28T07:16:53.044Z",
        "dateUpdated": "2016-01-28T07:16:53.044Z"
      },
      {
        "href": "//rwcbook06.herokuapp.com/task/1xya56y8ak1",
        "id": "1xya56y8ak1",
        "title": "Validate client-side code changes",
        "completeFlag": "true",
        "assignedUser": "",
        "dateCreated": "2016-01-14T17:46:32.384Z",
        "dateUpdated": "2016-01-16T04:50:57.618Z"
      }
    ]
  }
}

Our HAL client takes advantage of the _embedded objects and renders them on screen. That’s handled by the embedded routine, which looks like this:

// handle any embedded content
function embedded() {
  var elm, embeds, links;
  var segment, table, tr;

  elm = d.find("embedded");
  d.clear(elm);

  if(g.hal._embedded) {
    embeds = g.hal._embedded;
    for(var coll in embeds) { 

      p = d.para({text:coll, className:"ui header segment"});
      d.push(p,elm);

      // get all the objects in each collection
      items = embeds[coll];
      for(var itm of items) { 
        segment = d.node("div");
        segment.className = "ui segment";
        links = d.node("div");
        links.id = itm.id;
        d.push(links,segment);

        // emit all the properties for this item
        table = d.node("table"); 
        table.className = "ui very basic collapsing celled table";
        for(var prop of g.fields[g.context]) {
          if(itm[prop]) {
            tr = d.data_row({className:"property "+prop,text:prop+" ",
            value:itm[prop]+" "});
            d.push(tr,table);
          }
        }

        // push the item element to the page
        d.push(table,segment);
        d.push(segment, elm);

        // emit any item-level links
        selectLinks("item",itm.id, itm); 
      }
    }
  }
}

Here is a quick rundown of what’s happening in this routine:

Our embedded routine is able to handle multiple object collections in the response since the HAL spec allows this.

After collecting a set of objects, the code loops through each item in the collection for rendering.

Each of the embedded objects has their properties rendered within an HTML table.

And, lastly, any item-level links (from the _link collection) associated with the object are rendered, too.

Figure 4-3 shows a screenshot of our HAL client rendering a list of User objects.

Figure 4-3. Rendering a list of user objects with the HAL client

We have one more HAL element to deal with: Properties.

Properties

The HAL design includes support for sending objects or name–value pairs at the root level of the response. We saw an example of this earlier in Example 4-1. Our routine to handle these root elements is the properties function:

// emit any root-level properties
function properties() {
  var elm, coll;
  var segment, table, tr;

  elm = d.find("properties");
  d.clear(elm);
  segment = d.node("div");
  segment.className = "ui segment";
  if(g.hal && g.hal.id) { 
    links = d.node("div");
    links.id = g.hal.id;
    d.push(links,segment);
  }

  table = d.node("table");
  table.className = "ui very basic collapsing celled table";

  for(var prop of g.fields[g.context]) { 
    if(g.hal[prop]) {
      tr = d.data_row({className:"property "+prop,text:prop+" ",
        value:g.hal[prop]+" "});
      d.push(tr,table);
    }
  }

  d.push(table,segment);
  d.push(segment,elm);

  // emit any item-level links
  if(g.hal && g.hal.id) {
    selectLinks("item",g.hal.id, g.hal); 
  }
}

This routine is a bit less busy than the one handling the _links section.

First (at ), we confirm that we have one or more root level properties. Note the check for hal.id. This is a specific bit of knowledge of TPS Objects (they always have an id property) baked into the client. This would not work with just any HAL service response. Once we have a set of properties, we loop through the internal collection of fields for this context () using the g.fields[g.context] state value and only display properties the client knows about ahead of time. Finally, at , we insert any item-level links associated with this object. This is another TPS-specific element.

Figure 4-4 shows the HAL client rendering a single Task record.

That covers all the HAL response elements. But we still have a very important aspect of the web client that we have not shown: handling the Actions for Tasks and Users. You may recall that HAL doesn’t include any Action metadata in responses. It is up to the client application to handle these details.

Figure 4-4. Rendering a single item in HAL

Handling Actions for HAL

Since HAL doesn’t include Action details such as HTTP methods and arguments, our client needs to handle these instead. For the JSON client, we used a set of action objects to hold all the information (see “Addresses”). In the HAL client, we’ll do something similar. Since HAL links all have a unique identifier, we can use that identifier as a pointer to a list of Action definitions in code. And we can write a short routine to access these definitions. I created a small halForms JavaScript library for this.

Here is an example of the halForms Action definition:

{
  rel:"/files/hal-task-edit", 
  method:"put", 
  properties:   [ 
    {name:"id",required:true, value:"{id}", prompt:"ID", readOnly:true},
    {name:"title",required:true, value:"{title}", prompt:"Title"},
    {name:"tags", value:"{tags}", prompt:"Tags"},
    {name:"completeFlag",value:"{completeFlag}", prompt:"Completed"},
    {name:"assignedUser",value:"{assignedUser}", prompt:"Assigned User"}
  ]
};

Note the use of the rel property to hold the Action identifier at . This is used to match the same value found in a link element in the _links section of a HAL response. The HTTP method to use () and all the input arguments () are included, too. There is an Action definition for every query and write operation documented for the TPS web API. These are then accessed at runtime when someone clicks on an action link in the user interface.

To use these at runtime in the HAL client, every link in the UI is tied to a single function—the halLink function. That function looks like this:

// handle GET for links
function halLink(e) {
  var elm, form, href, accept;

  elm = e.target;
  accept = elm.getAttribute("type");

  form = forms.lookUp(elm.rel); 
  if(form && form!==null) {
    halShowForm(form, elm.href, elm.title); 
  }
  else {
    req(elm.href, "get", null, null, accept||g.ctype); 
  }
  return false;
}

As you can see, when a person clicks on a link in the HAL client, this code checks to see if there is an Action definition available () and, if it is, shows the HTML FORM in the UI (). Otherwise, the HAL client just executes a simple HTTP GET on the clicked link ().

The halShowForm routine knows how to convert the Action definition into a valid HTML FORM and can associate any current task or user record with the inputs (to make it easy to render existing objects for editing). Figure 4-5 shows a screen showing the TaskEdit operation at runtime.

Figure 4-5. Handling inputs in the HAL client

Quick Summary

In building our HAL client, we learned how to create a general HAL response parser that would render the data in a user interface. Along the way, we built a few key HAL-aware operations into our general library:

selectLinks

This routine was used to find and filter the collection of link elements in the HAL _links collection and render them when and where they are needed.

embedded

We used the HAL _embedded section to carry object lists (tasks and users) and wrote code that rendered these at runtime as well as any associated item-level links (using the selectLinks function again).

properties

Finally, the properties function handles any root-level name–value pairs (or objects) and also uses the selectLinks routine to render any item-level links associated with the root object.

There is more to the hal-client.js library that we didn’t cover here including the same low-level HTTP routines we used in all the other SPA examples and some HAL-specific functions to support URI Templates, manage screen display, and handle other small chores.

Now that we have a fully functioning HAL client, let’s introduce some change on the service API to see how our client adapts.

Adding an Action

For our example, let’s assume the TPS team decides to add a new Action element to the web API—the TaskMarkActive operation. This one allows people to mark any single Task object as “active” by setting the completeFlag="false". We can do something similar with the TaskMarkCompleted already.

case 'POST':
  if(parts[1] && parts[1].indexOf('?')===-1) {
    switch(parts[1].toLowerCase()) {
      case "completed":
        markCompleted(req, res, respond, parts[2]);
        break;
      case "active":
        markActive(req, res, respond, parts[2]); 
        break;
      case "assign":
        assignUser(req, res, respond, parts[2]);
        break;
      default:
        respond(req, res,
          utils.errorResponse(req, res, 'Method Not Allowed', 405)
        );
    }

{
  "_links": {
    "collection": {
      "href": "http://localhost:8181/task/",
      "title": "Tasks",
      "templated": false,
      "target": "app menu hal"
    },
    "http://localhost:8181/files/hal-task-item": {
      "href": "http://localhost:8181/task/{key}",
      "title": "Detail",
      "templated": true,
      "target": "item hal"
    },
    "http://localhost:8181/files/hal-task-edit": {
      "href": "http://localhost:8181/task/{key}",
      "title": "Edit Task",
      "templated": true,
      "target": "item edit hal"
    },
    "http://localhost:8181/files/hal-task-remove": {
      "href": "http://localhost:8181/task/{key}",
      "title": "Remove Task",
      "templated": true,
      "target": "item edit hal"
    },
    "http://localhost:8181/files/hal-task-markcompleted": {
      "href": "http://localhost:8181/task/completed/{id}",
      "title": "Mark Completed",
      "templated": true,
      "target": "item completed edit post form hal"
    },
    "http://localhost:8181/files/hal-task-assignuser": {
      "href": "http://localhost:8181/task/assign/{id}",
      "title": "Assign User",
      "templated": true,
      "target": "item assign edit post form hal"
    },
    "http://localhost:8181/files/hal-task-markactive": { 
      "href": "http://localhost:8181/task/active/{id}",
      "title": "Mark Active",
      "templated": true,
      "target": "item active edit post form hal"
    },
    "http://localhost:8181/files/hal-task-task": [
      {
        "href": "//localhost:8181/task/1m80s2qgsv5",
        "title": "Run client-side tests"
      }
    ]
  },
  "id": "1m80s2qgsv5",
  "title": "Run client-side tests",
  "tags": "test",
  "completeFlag": "false",
  "assignedUser": "alice",
  "dateCreated": "2016-01-28T07:14:07.775Z",
  "dateUpdated": "2016-01-31T22:30:25.578Z"
}

The failing HAL client

The new link (“Mark Active”) will appear in the HAL client automatically since HAL understands how to deal with links. However, since the TaskMarkActive operation requires using an HTTP POST, the HAL client fails (see Figure 4-6).

Figure 4-6. HAL client fails on new Action

HAL responses don’t include Action definitions. For this new functionality, it is not enough to recognize the link, the client also needs to know what to do with it. And that only appears in the human documentation.

Recoding the Action definition on the HAL client

To fix this, we need to translate the new API documentation into a new Action definition and recode and redeploy our app again:

{
  rel:"/files/hal-task-markactive", 
  method:"post",
  properties: [
    {name:"id",value:"{id}", prompt:"ID",readOnly:true},
    {name:"completeFlag",value:"false", prompt:"Completed",readOnly:true}
  ]
};

Note in the preceding Action definition (), the rel value is set to match that of the link identifier in the HAL response output by the TPS web API.

Now, as Figure 4-7 shows, the HAL client knows how to handle the new link, shows the proper HTML form, and successfully marks the Task object as “active.”

Figure 4-7. New Action definition for HAL client

We can actually improve the HAL client’s ability to deal with unexpected Actions by relying on a custom HAL extension. We’ll take a quick look at that in the last section of this chapter.

The Specification

The HAL-FORMS specification is a more formalized version of the in-app Action definitions used earlier in this chapter. However, that simple JSON object has been updated to be more in line with Mike Kelly’s HAL specification and offers a few more future possibilities including the ability to load the definitions on-demand at runtime.

{
  "_links" : {
    "self": {
      "href": "/files/hal-task-create-form" 
    }
  },
  "_templates" : {
    "default" : {
      "title" : "Add Task",
      "method":"post", 
      "properties": [ 
        {"name":"title", "required":true, "value":"", "prompt":"Title"},
        {"name":"tags", "value":"", "prompt":"Tags"},
        {"name":"completeFlag", "required":false,
        "value":"false", "prompt":"Completed"}
      ]
    }
  }
}

"http://localhost:8181/files/hal-task-create-form": {
  "href": "http://localhost:8181/task/",
  "title": "Add Task",
  "templated": false
},

GET /files/hal-task-create-form HTTP/1.1
accept: application/prs.hal-forms+json
...

HTTP/1.1 200 OK
content-type: application/prs.hal-forms+json
....
{
  ... HAL-FORMS document here
}

The Implementation

Adding support for the HAL-FORMS extension at runtime is pretty simple. I needed to make some adjustments to the low-level HTTP calls to make them aware of HAL-FORMS responses. I also needed to modify the way the client responds to the initial link clicks (halLink), and to update the way the halShowForm routine worked to make sure it included information from the new HAL-FORMS document.

Here is an excerpt from the client library that shows the halLink routine and related code:

// handle GET for links
function halLink(e) {
  var elm, form, href, accept, fset;

  elm = e.target;
  accept = elm.getAttribute("type");

  // build stateless block 
  fset = {};
  fset.rel = elm.rel;
  fset.href = elm.href;
  fset.title = elm.title;
  fset.accept = elm.accept;
  fset.func = halFormResponse;

  // execute check for a form
  formLookUp(fset); 

  return false;
}

function formLookUp(fset) { 
  req(fset.rel, "get", null, null, "application/prs.hal-forms+json", fset);
}

function halFormResponse(form, fset) {
  if(form && form!==null && !form.error && fset.status<400)  {
    // valid form resonse? show it
    halShowForm(form, fset.href, fset.title); 
  }
  else {
    // must be a simple HAL response, then
    req(fset.href, "get", null, null, fset.accept||g.ctype, null); 
  }
}

The highlights are:

Build up a shared block of properties to send to the low-level HTTP caller.

Use that information to make a request for a HAL-FORMS document.

This is the line that makes the HAL-FORMS request (not the media type string).

If a valid HAL-FORMS document was returned, pass it to the halShowForm routine.

Otherwise, just perform a simple HTTP GET on the original URL that initiated the click.

There is more to making the mod work and you can check out the associated repo for details.

So, with this new extension, I’ve moved the Action definitions to a standalone set of files that can be updated by the API service in a way that our HAL client application can understand and use safely without the need to recode and redeploy the client code. That means when the service API adds new functionality—for example, MarkTaskActive or any other new interaction—the service can just offer up a new HAL-FORMS document and the existing client will be able to handle the details (e.g., URL, HTTP method, arguments, etc.).

Image Credits

• Diogo Lucas: Figure 4-1