From 5c99243cdcd05136d5716dea9ef44ad72135a1f2 Mon Sep 17 00:00:00 2001 From: Mike Gerwitz Date: Tue, 20 Jun 2017 12:55:20 -0400 Subject: [PATCH] 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 | 2 +- doc/dapi.texi | 149 ++++++++++++++++++++++++++++++++++++++++++++++++ doc/design.texi | 6 ++ doc/liza.texi | 2 + 4 files changed, 158 insertions(+), 1 deletion(-) create mode 100644 doc/dapi.texi 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