Next: , Previous: , Up: Top   [Contents][Index]

5 Data API

This system has maintenance concerns. 10

There isn’t much here yet. Maybe you can help?

The Data API is a declarative abstraction for accessing and processing remote data (e.g. a RESTful service). The name stems from how it is used—to declare an remote API’s inputs and outputs.

This system is generally used indirectly through the Program XML.11

All interaction with this system should be had through the DataApiManager.

The DataApiManager manages the entire operation—from triggering the initial request, to performing mapping, to populating bucket data. It takes only a DataApiFactory and Data API definitions.

Definitions have the following schema:12

  "type": "string",
  "source": "string",
  "method": "string",
  "params": {
    ["string(name)"]: {
      "name": "string(name)",
      "default": {
        "type": "string",
        "value": "string"
  "retvals": [ "string", ... ],
  "static": [
      ["string(param)"]: "string",
  "static_nonempty": boolean,
  "static_multiple": boolean

Each of the above fields are defined by:


Any type supported by DataApiFactory (e.g. ‘rest’).


Type-specific source of data. For e.g. ‘rest’, this is a URI.


Type-specific method for interacting with the API. For e.g. ‘rest’, this is an HTTP method.


Key-value mapping of input parameter names (as received by ‘source’) to their default values. These inputs must be populated by the caller at the time of the request.


Array of fields returned by the data source.


Static values to prepend to the returned data. This is often used for adding “please select” text, for example.


Whether statics should be added when there is return data; Otherwise, they will be added only if the response yields no results.


Whether statics should be added only if multiple data are returned. For example, a “please select” is only useful if there is more than one option for the user to select from. When ‘true’, this has the convenient side-effect of auto-selecting the only result.

An example definition appears in Figure 5.1

    "type": "rest",
    "source": "/foo/city",
    "method": "post",
    "params": {
      "getVal": {
        "name": "getVal",
        "default": {
          "type": "string",
          "value": "getCityOptions"
      "zipcode": {
        "name": "zipcode",
        "default": {
            "type": "ref",
            "value": ""
    "retvals": [ "city", "id", "state", "county", "country" ],
    "static": [ {
      "city": "(Please Select)",
      "id": "",
      "state": "",
      "county": "",
      "country": ""
    } ],
    "static_nonempty": false,
    "static_multiple": true

Figure 5.1: Example Data API definition



This is a complex system with too much logic lying in DataApiManager (having been extracted from its old home in Program ).


See ‘Data API’ in the Liza Program UI Compiler manual.


There are poor design decisions that will likely persist indefinitely because of integration with other systems, so future extensions may be messy (especially in the case of ‘retvals’).

Next: , Previous: , Up: Top   [Contents][Index]