Recognizing objects

Lucky for us, the TPS web API has only two main objects (Task and User) and each of them are just a set of name–value pairs. This simple design makes our sample apps easy to work with and explore. However, most non-trivial production apps are likely to have several objects and tens (possibly hundreds) of properties.

As we saw in Chapter 1, the TPS web API responses are simple arrays:

{
  "task": [
    {
      "id": "137h96l7mpv",
      "title": "LAX",
      "completeFlag": "true",
      "assignedUser": "bob",
      "dateCreated": "2016-01-14T17:48:42.083Z",
      "dateUpdated": "2016-01-27T22:03:02.850Z"
    },
    {
      "id": "1gg1v4x46cf",
      "title": "YVR",
      "completeFlag": "false",
      "assignedUser": "carol",
      "dateCreated": "2016-01-14T18:03:18.804Z",
      "dateUpdated": "2016-01-27T17:45:46.597Z"
    },
    .... more TASK objects here
   ]
 }

Our client app will need to recognize the "task" array name and act accordingly at runtime. One good way to do this is to use the object identifier as a context switch. When our app sees "task":[…] in the response, it will switch to “task-mode” and display the data (and possible actions) related to tasks. When the server response contains "user":[…], the app can switch to “user-mode.” Of course, our app won’t know what to do if a service response contains "note ":[…] or some other unknown context value. For now, we’ll need to ignore anything we don’t recognize.

Displaying data

Just knowing the objects and their properties is not enough. Client applications also need to know how to deal with them when they show up in an API response. For example, whether to show the data item at all, and if so, which properties to display, the human prompts associated with the properties, and so on.

For example, the Task object emitted by the TPS web API looks like this:

{
  "id": "137h96l7mpv",
  "title": "Review API Design",
  "completeFlag": "false",
  "assignedUser": "bob",
  "dateCreated": "2016-05-14T17:48:42.083Z",
  "dateUpdated": "2016-05-27T22:03:02.850Z"
},

For our client app, we’ve decided to not display the dateCreated and dateUpdated fields. In fact, we’ll need to keep track of which fields to hide and which to show for all the TPS objects.

We also need to decide which prompts to display for each property in the TPS Task and User objects. Most of the time, client-side developers need to keep an internal set of prompts (possibly even tagged for more than one language) and map those prompts to the property names at runtime. For our simple app, we’ll just use a CSS trick to capitalize the property names when displaying them as prompts (see in the code provided in Example 2-1).

span.prompt {
  display:block;
  width:125px;
  font-weight:bold;
  text-align:right;
  text-transform:capitalize; 
}

This works because we only need to support a single language and we’re just working with a simple demo app. Production apps will need more attention to detail on this point. We’ll see a more robust way to handle onscreen displays in Chapter 6, Siren Clients.

So, our client app will keep track of all the important JSON objects coming from the server, know how to handle each of them, and know which properties to display and what prompts are associated with them.

The next thing to deal with is the object’s Addresses—their URLs.

TPS objects

The TPS objects (Task and User) are simple name–value pairs. So, all our client app needs to know are the properties of each object that need to be rendered on screen. For example, all TPS objects have dateCreated and dateUpdated properties, but our client doesn’t need to deal with them.

This app uses a simple array to contain all the object properties it needs to know about:

global.fields.task = ["id","title","completeFlag","assignedUser"];
global.fields.user = ["nick","name","password"];

Now, whenever parsing incoming objects, the client app will compare the property on the object with its own list of properties and ignore any incoming property it doesn’t already know about.

An example of how this works can be seen in the code that handles on-screen rendering of objects in the response:

// g = global storage
// d = domHelper library

// handle item collection
function items() {
  var rsp, flds, elm, coll;
  var ul, li, dl, dt, dd, p;

  rsp = g.rsp[g.context]; 
  flds = g.fields[g.context];

  elm = d.find("items");
  d.clear(elm);
  ul = d.node("ul");

  coll = rsp;
  for(var item of coll) {
    li = d.node("li");
    dl = d.node("dl");
    dt = d.node("dt");

    // emit the data elements
    dd = d.node("dd");
    for(var f of flds) { 
      p = d.data({text:f, value:item[f]});
      d.push(p,dd);
    }
    d.push(dt, dl, dd, li, lu);
  }
  d.push(ul,elm);
}

Note (in ) the first step in the routine is to use the shared context value to locate the data in the response (rsp) and select the internal properties to use when inspecting the data (flds). This information is used (in ) to make sure to only render the fields the client decides is appropriate (see Figure 2-4).

Figure 2-4. Rendering task items in the JSON client

Addresses and actions

This client app stores both the addresses (URLs) and actions (HTTP method and parameter information) in a single internal collection called actions. There is additional metadata about each action that indicates when it should be rendered (based on context information) and how it should be executed (e.g., as a simple link, form, or direct HTTP method call).

The list of actions for the TPS web API is rather long (17 separate actions), but the following code snippet gives you a good idea of how they are stored in the client app:

// task context actions
global.actions.task = {
  tasks:   {target:"app", func:httpGet, href:"/task/", prompt:"Tasks"}, 
  active:  {target:"list", func:httpGet, href:"/task/?completeFlag=false",
             prompt:"Active Tasks"
           },
  byTitle: {target:"list", func:jsonForm, href:"/task", 
             prompt:"By Title", method:"GET",
             args:{
               title: {value:"", prompt:"Title", required:true}
             }
           },
  add:     {target:"list", func:jsonForm, href:"/task/", 
             prompt:"Add Task", method:"POST",
             args:{
               title: {value:"", prompt:"Title", required:true},
               completeFlag: {value:"", prompt:"completeFlag"}
             }
           },
  item:    {target:"item", func:httpGet, href:"/task/{id}", prompt:"Item"},
  edit:    {target:"single", func:jsonForm, href:"/task/{id}", 
             prompt:"Edit", method:"PUT",
             args:{
               id: {value:"{id}", prompt:"Id", readOnly:true},
               title: {value:"{title}", prompt:"Title", required:true},
               completeFlag: {value:"{completeFlag}", prompt:"completeFlag"}
             }
           },
  del:     {target:"single", func:httpDelete, href:"/task/{id}", 
             prompt:"Delete", method:"DELETE", args:{}
           },
};

In the preceding code snippet, you can see a simple, safe, read-only action () as well as a safe action that requires user input (). There are also the classic CRUD actions (, , and ) with the expected HTTP method names, prompts, and (where appropriate) argument lists. These action definitions are selected based on runtime context information. For example, the target property indicates which actions are appropriate for app-level, list-level, item-level, and even single-item level context.

Here’s an example of the code that uses context information and scans the list of actions to render list-level links:

 // d = domHelper library

 // handle list-level actions
function actions() {
  var actions;
  var elm, coll;
  var ul, li, a;

  elm = d.find("actions");
  d.clear(elm);
  ul = d.node("ul");

  actions = g.actions[g.context]; 
  for(var act in actions) {
    link = actions[act];
    if(link.target==="list") { 
      li = d.node("li");
      a = d.anchor({
        href:link.href,
        rel:"collection",
        className:"action",
        text:link.prompt
      });
      a.onclick = link.func;
      a.setAttribute("method",(link.method||"GET"));
      a.setAttribute("args",(link.args?JSON.stringify(link.args):"{}"));
      d.push(a,li);
      d.push(li, ul);
    }
  }
  d.push(ul, elm);
}

You can see in this code that both the object context () and the internal render context () are used to select only the links appropriate for display at the moment.

The actions that contain argument details will be rendered at runtime using HTML <form> elements (see Figure 2-5). The code that handles this is shown here:

// d = domHelper library

// render inputs
coll = JSON.parse(link.getAttribute("args")); 
for(var prop in coll) {
  val = coll[prop].value;
  if(rsp[0][prop]) {
    val = val.replace("{"+prop+"}",rsp[0][prop]); 
  }
  p = d.input({ 
    prompt:coll[prop].prompt,
    name:prop,
    value:val,
    required:coll[prop].required,
    readOnly:coll[prop].readOnly,
    pattern:coll[prop].pattern
  });
  d.push(p,fs);
}

In the small snippet just shown, you can see the collection of args () from the action definition is used to create HTML form inputs. At you can see that any current object is used to populate the value of the inputs before the actual HTML input element is created (). Note the inclusion of the HTML5 properties required, readonly, and pattern in order to improve the client-side user experience, too.

Figure 2-5. JSON client rendering a form

Quick summary

There is more to the json-client.js library that we won’t cover here, including all the Ajax-related code to handle HTTP requests and responses. Even with all the low-level HTTP code, the total size of the library is around 500 lines of JavaScript—and that includes extensive comments. In fact, the breakdown of the various parts of the client are worth noting.

HTTP-level handlers

For example, the Ajax-related low-level HTTP code takes up about 100 lines. This code would typically be handled by jQuery or other framework libraries. Also, this code will not grow or shrink as the number of unique objects, addresses, and actions changes within the web API. The HTTP-handling code is a fixed size.

Parsing and rendering

The heart of the JSON client code is about 300 lines that handle the parsing and rendering of the user interface. That content is also unlikely to change as the web API objects and functionality changes. However, this part of the codebase could grow as more client-side UX features are added to the library.

Web API objects, and actions

Finally, the other large portion of the code library is the 150 or so lines of JavaScript used to declare the TPS web API objects, address, and action configuration. This is the part of the library that will be directly affected by the web API objects and actions. As the API functionality grows, this code must grow, too.

This last item points to an important aspect of JSON API clients: changing the backend API will force the client frontend to change, too. I’ve done my best to isolate those changes to a single section of the library, but I can’t eliminate the need for these changes to occur since the client code has all the service’s Objects, Addresses, and Actions baked directly into the code.

So, let’s make some changes to the backend web API and see how this JSON client handles it.

Changing the TPS web API

The process of changing the TPS web API to support the new tag functionality is not too complex. We’ll need to:

1. Add the tag property to the Task storage definition.

2. Introduce a new query for Task storage and export that via HTTP.

To add the new tag field to the server’s storage support, we first need to update a line of code that defines the valid fields for the Task object ().

  // task-component.js
  // valid fields for this record
  props = [
    "id",
    "title",
    "tag", 
    "completeFlag",
    "assignedUser",
    "dateCreated",
    "dateUpdated"
  ];

Next, we need to modify the validation rules for adding and updating Task objects on the server. The following code snippet shows the addTask routine with the new tag field (). A similar change was made to the updateTask routine, too.

function addTask(elm, task, props) {
  var rtn, item;

  item = {}
  item.tags = (task.tags||""); 
  item.title = (task.title||"");
  item.assignedUser = (task.assignedUser||"");
  item.completeFlag = (task.completeFlag||"false");
  if(item.completeFlag!=="false" && item.completeFlag!=="true") {
    item.completeFlag="false";
  }
  if(item.title === "") {
    rtn = utils.exception("Missing Title");
  }
  else {
    storage(elm, 'add', utils.setProps(item, props));
  }

  return rtn;
}

Testing the Updated TPS web API

With these changes in place, we can use the curl command-line app to validate our changes. A command to create a record with the tag value set to "test" looks like this:

curl -X POST -H "content-type:application/json" -d
  '{"title":"Run remote client tests","tags":"test"}'
  http://localhost:8181/task/

and creates a new task record that looks like this:

{
  "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"
}

Assuming several new records were created, executing the filter query would look like this:

curl http://localhost:8181/task/?tags=test

and would return one or more task records with the tag value that contains "test":

{
  "task": [
    {
      "id": "1m80s2qgsv5",
      "title": "Run client-side tests",
      "tags": "test client",
      "completeFlag": "false",
      "assignedUser": "",
      "dateCreated": "2016-01-28T07:14:07.775Z",
      "dateUpdated": "2016-01-28T07:14:07.775Z"
    },
    {
      "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"
    },
    {
      "id": "242hnkcko0f",
      "title": "Run remote client tests",
      "tags": "test remote",
      "completeFlag": "false",
      "assignedUser": "",
      "dateCreated": "2016-01-28T07:19:47.916Z",
      "dateUpdated": "2016-01-28T07:19:47.916Z"
    }
  ]
}

With the TPS web API updated and validated, we next need to see how the JSON API client handles the change in production.

Testing the JSON API client

The easiest way to test the JSON API client’s support for the new tag field and filter option is to simply run the existing client and check the results. Figure 2-6 shows a screenshot from the JSON API client making a request to the new TPS web API server.

Figure 2-6. JSON API client without tag support

As you can see from the screenshot, even though the new task records appear in the client, the tag field is missing from the display as well as the new filter option. The good news is our JSON client didn’t crash when the new feature was added. The bad news is our client simply ignored the new functionality.

The only way our JSON client will be able to take advantage of this new option is to recode and redeploy a new version of the app into production.