Mike Gerwitz

Activist for User Freedom

aboutsummaryrefslogtreecommitdiffstats
diff options
context:
space:
mode:
Diffstat (limited to 'doc/dapi.texi')
-rw-r--r--doc/dapi.texi149
1 files changed, 149 insertions, 0 deletions
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