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:

type

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

source

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

method

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

params

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.

retvals

Array of fields returned by the data source.

static

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

static_nonempty

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

static_multiple

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


Footnotes

(10)

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

(11)

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

(12)

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]