Mike Gerwitz

Activist for User Freedom

aboutsummaryrefslogtreecommitdiffstats
blob: ca61c921ba4f207e6dec6338e0e0f9e1effabcfa (plain)
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
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