liza/doc/dapi.texi

@c  This document is part of the Liza Data Collection Framework manual.
@c  Copyright (C) 2017 R-T Specialty, LLC.
@c
@c    Permission is granted to copy, distribute and/or modify this document
@c    under the terms of the GNU Free Documentation License, Version 1.3
@c    or any later version published by the Free Software Foundation;
@c    with no Invariant Sections, no Front-Cover Texts, and no Back-Cover
@c    Texts.  A copy of the license is included in the section entitled ``GNU
@c    Free Documentation License''.

@node Data API
@chapter Data API
@maintenance{This is a complex system with too much logic lying in
               @srcrefjs{dapi,DataApiManager} (having been extracted
               from its old home in @srcrefjs{program,Program} ).}

@helpwanted{}

The @dfn{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@mdash{
  }to declare an remote API's inputs and outputs.

This system is generally used indirectly through the @progxmlref{}.@footnote{
  @proguicxref{Data API}.}

@tip{All interaction with this system should be had through the
  @srcrefjs{dapi,DataApiManager}.}

The @srcrefjs{dapi,DataApiManager} manages the entire operation@mdash{
  }from triggering the initial request,
    to performing mapping,
    to populating bucket data.
It takes only a @srcrefjs{dapi,DataApiFactory} and @dapi{} definitions.

Definitions have the following schema:@footnote{
  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
      @samp{retvals}).
}

@verbatim
{
  "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
}
@end verbatim

Each of the above fields are defined by:

@table @code
  @item type
  Any type supported by @srcrefjs{dapi,DataApiFactory} (e.g. @samp{rest}).

  @item source
  Type-specific source of data.
  For e.g. @samp{rest}, this is a URI.

  @item method
  Type-specific method for interacting with the API.
  For e.g. @samp{rest}, this is an HTTP@tie{}method.

  @item params
  Key-value mapping of input parameter names (as received by @samp{source})
    to their default values.
  These inputs must be populated by the caller at the time of the request.

  @item retvals
  Array of fields returned by the data source.

  @item static
  Static values to prepend to the returned data.
  This is often used for adding ``please select'' text, for example.

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

  @item 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 @samp{true},
    this has the convenient side-effect of auto-selecting the only
    result.
@end table

An example definition appears in @ref{f:dapi-ex}

@float Figure, f:dapi-ex
@example
  @{
    "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
  @},
@end example
@caption{Example @dapi{} definition}
@end float