Mike Gerwitz

Activist for User Freedom

aboutsummaryrefslogtreecommitdiffstats
path: root/doc
diff options
context:
space:
mode:
authorMike Gerwitz <gerwitzm@lovullo.com>2017-06-20 12:55:20 -0400
committerMike Gerwitz <gerwitzm@lovullo.com>2017-06-21 10:52:46 -0400
commit5c99243cdcd05136d5716dea9ef44ad72135a1f2 (patch)
treebbef8a8df8ce7dd93874dae714552b5d818ece14 /doc
parentbe0121d8cba9d6ed5b6a014fa3c03bc9524251f3 (diff)
downloadliza-5c99243cdcd05136d5716dea9ef44ad72135a1f2.tar.gz
liza-5c99243cdcd05136d5716dea9ef44ad72135a1f2.tar.bz2
liza-5c99243cdcd05136d5716dea9ef44ad72135a1f2.zip
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.
Diffstat (limited to 'doc')
-rw-r--r--doc/Makefile.am2
-rw-r--r--doc/dapi.texi149
-rw-r--r--doc/design.texi6
-rw-r--r--doc/liza.texi2
4 files changed, 158 insertions, 1 deletions
diff --git a/doc/Makefile.am b/doc/Makefile.am
index 2e84fc2..9221169 100644
--- a/doc/Makefile.am
+++ b/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
diff --git a/doc/dapi.texi b/doc/dapi.texi
new file mode 100644
index 0000000..ca61c92
--- /dev/null
+++ b/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
diff --git a/doc/design.texi b/doc/design.texi
index c054464..20f3ed9 100644
--- a/doc/design.texi
+++ b/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.
diff --git a/doc/liza.texi b/doc/liza.texi
index e8591a8..38cb00a 100644
--- a/doc/liza.texi
+++ b/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