150 lines
4.1 KiB
Plaintext
150 lines
4.1 KiB
Plaintext
@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
|