doc: Add beginning of dapi documentation

* doc/Makefile.am (liza_TEXINFOS) [dapi.texi]: Include file.
* doc/dapi.texi: Add file.
* doc/design.texi: Add mention in list and reference chapter.
* doc/liza.texi: Reference chapter.

doc/Makefile.am

@@ -23,7 +23,7 @@ MAKEINFOHTML = $(MAKEINFO) --html --css-include liza.css
 info_TEXINFOS = liza.texi
 liza_TEXINFOS = macros.texi config.texi liza.css \
                 design.texi assert.texi bucket.texi client.texi \
-                pred.texi program.texi validation.texi \
+                dapi.texi pred.texi program.texi validation.texi \
                 diagram/event-graph.svg
 
 diagram/%.svg: diagram/%.dot

doc/dapi.texi

@@ -0,0 +1,149 @@
+@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

doc/design.texi

@@ -47,6 +47,12 @@ The main components of the system are:
     etc.
   @xref{Client}.
 
+  @cindex Data API
+  @item Data API
+  Declarative abstraction for accessing and processing remote data
+    (e.g. a RESTful service).
+  @xref{Data API}.
+
   @cindex Developer Dialog
   @item Developer Dialog
   Renders information about the system for debugging the client.

doc/liza.texi

@@ -79,6 +79,7 @@ Free Documentation License''.
 * Assertions::
 * Bucket::
 * Client::
+* Data API::
 * Predicate System::
 * Program::
 * Validation::
@@ -98,6 +99,7 @@ Free Documentation License''.
 @include assert.texi
 @include bucket.texi
 @include client.texi
+@include dapi.texi
 @include pred.texi
 @include program.texi
 @include validation.texi