PROTOCOL.md 8.8 KB
Newer Older
1
2
<!-- -*- markdown -*- -->

3
# Client/Server Protocol
Carsten  Rose's avatar
Carsten Rose committed
4

5

Rafael Ostertag's avatar
Rafael Ostertag committed
6
## General Protocol
Carsten  Rose's avatar
Carsten Rose committed
7

Rafael Ostertag's avatar
Rafael Ostertag committed
8
9
The Client may asynchronously send requests to the Server. The Server
is expected to return responses as outlined below.
Carsten  Rose's avatar
Carsten Rose committed
10

Rafael Ostertag's avatar
Rafael Ostertag committed
11
12
13
The response must contain at least a [Minimal Response]. Depending on
the request, it may provide additional responses as outlined in this
section.
14

Carsten  Rose's avatar
Carsten Rose committed
15

Rafael Ostertag's avatar
Rafael Ostertag committed
16
### Minimal Response
17
18
19

Asynchronous request (read AJAX) initiated by the Client receive a
JSON Response from the server containing at least:
Carsten  Rose's avatar
Carsten Rose committed
20

21
22
23
	{
		"status": "success"|"error",
		"message": "<message>"
Carsten  Rose's avatar
Carsten Rose committed
24
25
    }
   
26
27
28
29
`status` indicates whether or not the request has been fullfiled by
the server (`"success"`) or encountered an error (`"error"`). On
`"error"` the Client must display `"<message>"` to the user. On
`"success"`, the Client may display `"<message>"` to the user.
30
31
32

Depending on the request, the server may provide additional
information in the response, as outlined below.
33
34


Rafael Ostertag's avatar
Rafael Ostertag committed
35
36
37
38
39
40
### HTML Form Element Validation Response

The Server may perform a serverside validation of values submitted as
part of a HTML Form submission. If the validation fails, it may notify
the Client by adding following name/value pairs to the response JSON
Stream
41
42
43
44
45
46
47
48
49
50
51
52

	{
		"status": "error",
		...
	    "field-name": "<field name>",
		"field-message": "<message>",
		...
	}
	
Only one validation failure per request can be reported to Client.

The Server is expected to set the status `"status"` to `"error"`, and
Rafael Ostertag's avatar
Rafael Ostertag committed
53
54
the Client is expected to treat the error as explained in [Minimal Response]
and must obey the rules of redirection as explained in [Redirection Response].
55
56
57
58
59
60
61
62
63
64

The Client must visibly highlight the HTML Form Element that caused the
validation failure.

`"field-name"`
:	The value of the `name` attribute of the HTML Form Element that
	caused the validation failure.
	
`"field-message"`
:	Message to the User, indicating the nature of the failure.
Rafael Ostertag's avatar
Rafael Ostertag committed
65
66
67


### Form Group Configuration Response
68
69

As part of the server response, the JSON stream may contain a key
Rafael Ostertag's avatar
Rafael Ostertag committed
70
71
72
73
`form-update`. This response is used to reconfigure HTML Form Elements
and Form Groups on the clientside, based on conditions evaluated on
the serverside. It contains an array of objects
having the following structure
74
75

    {
76
77
78
79
80
81
82
83
84
85
86
87
		...
		"form-update" : [
			{
				"form-element": "<element_name>",
				"hidden": true | false,
				"disabled": true | false,
				"required": true | false,
				"value": <value>
			},
			...
		],
		...
88
89
90
    }

`"form-element"`
91
:	 the name of the HTML Form Element as it appears in the `name` attribute.
92
93

`"hidden"`
94
:   whether the Form Group is visible (value: `false`) or invisible (value: `true`).
95
96
97
98
99
	
`"disabled"`
:   whether or not the Form Element is disabled HTML-wise.

`"required"`
100
:   whether or not the Form Element receives the HTML5 `required` attribute.
101
102

`"value"`
Rafael Ostertag's avatar
Rafael Ostertag committed
103
104
:	For textual HTML Form Input elements, it is supposed to be a scalar
	value, which is set on the element.
105
	
Rafael Ostertag's avatar
Rafael Ostertag committed
106
107
108
109
	When `"form-element"` references a `<select>` element, a scalar
    value selects the corresponding value from the option list. In
    order to replace the entire option list, use an array of objects
    as value to `"value"`, having this format
110
111
	   
	    [
Rafael Ostertag's avatar
Rafael Ostertag committed
112
			...
113
114
115
116
117
118
119
120
121
122
			{
				"value": 100,
				"text": "a",
				"selected": true
			},
			{
				"value": 200,
				"text": "b",
				"selected": false
			}
Rafael Ostertag's avatar
Rafael Ostertag committed
123
			...
124
125
126
127
        ]
		
	`"select"` is optional, as is `"text"`. If `"text"` is omitted, it
    will be derived from value.
128
129
130
131
132
133
134
135
	
	HTML checkboxes are ticked with a `"value"` of `true`. They are
    unchecked with `false`.
	
	HTML radio buttons are activated by providing the value of the
    radio button `value`-attribute to be activated in `"value"`.
	

Rafael Ostertag's avatar
Rafael Ostertag committed
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
### Form Group Configuration Response

As part of the server response, the JSON stream may contain a key
`element-update`. This key stores information on how to modify HTML elements identified by `id`. Modifying in this 
context refers to:

 * Setting attribute values
 * Deleting attributes
 * Setting content of a HTML element.
 
The content of `element-update` is outlined below

    {
        ...
        "element-update" : {
            "<element_id1>": {
                "attr": {
                    "<attr_name1>": "<value1>" | null,
                    ...
                    "<attr_nameN>": "<valueN>" | null
                },
                "content": "<element_content>"
            },
            ...
            "<element_idN>": {
                "attr": {
                    "<attr_name1>": "<value1>" | null,
                    ...
                    "<attr_nameN>": "<valueN>" | null
                },
                "content": "<element_content>"
            }
        },
        ...
    }
    
The presence of `element-update` is optional. `<element_idN>` refers to the element's `id`-attribute value. It used 
to uniquely identify the HTML element in the DOM. The properties `"attr"` and `"content"` are both optional.

Supplying `null` as value for `"<attr_nameN>"` will remove the attribute from the HTLM element identified by 
`"<element_idN>"`.

If the element has no `"<attr_nameN>"` attribute, it will be created. In any case, the attribute's value will be set 
to the value specified by `"<valueN>"`. See above for handling of `null` value.

Rafael Ostertag's avatar
Rafael Ostertag committed
181
### Redirection Response
182
183

Depending on the request, the server may return redirection
Rafael Ostertag's avatar
Rafael Ostertag committed
184
information to the Client. It is up to the Client to respect the
185
186
187
188
189
190
redirection information.

The Client must not perform a redirect in case the status in
`"status"` is `"error"`.

The format of redirect information is outlined below
191
192
193
194
195
196
197
198
199
200

	{
		...
		"redirect": "no" | "url" | "client"
		"redirect-url": "<url>"
		...
	}
	

`"redirect"`
201
202
203
204
205
206
207
208
:	type of redirection. `"no"` advises the Client to stay on the
	Current Page. `"client"` advises the Client to decide where to
	redirect to. `"url"` advices the Client to redirect to the URL
	provided in `"redirect-url"`.
	
`"redirect-url"`
:	Used to provide an URL when `"redirect"` is set to `"url"`. It
	should be disregarded unless `"redirect"` is set to `"url"`.
Carsten  Rose's avatar
Carsten Rose committed
209
210


Rafael Ostertag's avatar
Rafael Ostertag committed
211
## API Endpoints
Carsten  Rose's avatar
Carsten Rose committed
212
213


Rafael Ostertag's avatar
Rafael Ostertag committed
214
### Form Update
Carsten  Rose's avatar
Carsten Rose committed
215

216
217
218
219
220
The Client may request an updated set of Form Group Configuration and
HTLM Element states. In order for the Server to compile the set of
Form Group Configuration and HTML Element states, it requires the
entire HTML Form in the POST body, without any HTML Input Elements of
type `file`.
221

Rafael Ostertag's avatar
Rafael Ostertag committed
222
223
The Client must include the SIP using an HTML Input Element (most
likely of `type` `hidden`).
Carsten  Rose's avatar
Carsten Rose committed
224

Rafael Ostertag's avatar
Rafael Ostertag committed
225
226
Request URL
:	api/load.php
Carsten  Rose's avatar
Carsten Rose committed
227

Rafael Ostertag's avatar
Rafael Ostertag committed
228
229
Request Method
:	POST
Carsten  Rose's avatar
Carsten Rose committed
230

Rafael Ostertag's avatar
Rafael Ostertag committed
231
232
URL Parameters
:	none
Carsten  Rose's avatar
Carsten Rose committed
233

Rafael Ostertag's avatar
Rafael Ostertag committed
234
235
236
Server Response
:   The response contains at least a [Minimal Response]. In addition,
	a [Form Group Configuration Response] may be included.
Carsten  Rose's avatar
Carsten Rose committed
237
238


Rafael Ostertag's avatar
Rafael Ostertag committed
239
### Form Save
Carsten  Rose's avatar
Carsten Rose committed
240

Rafael Ostertag's avatar
Rafael Ostertag committed
241
242
243
The Client submits the HTML Form for persitent storage to the
Server. The submission should not contain `<input>` HTML Elements of
type `file`.
Carsten  Rose's avatar
Carsten Rose committed
244

Rafael Ostertag's avatar
Rafael Ostertag committed
245
246
The Client must include the SIP using an HTML Input Element (most
likely of `type` `hidden`).
Carsten  Rose's avatar
Carsten Rose committed
247

Rafael Ostertag's avatar
Rafael Ostertag committed
248
249
Request URL
:	api/save.php
Carsten  Rose's avatar
Carsten Rose committed
250

Rafael Ostertag's avatar
Rafael Ostertag committed
251
252
Request Method
:	POST
Carsten  Rose's avatar
Carsten Rose committed
253

Rafael Ostertag's avatar
Rafael Ostertag committed
254
255
URL Parameters
:	none
Carsten  Rose's avatar
Carsten Rose committed
256

Rafael Ostertag's avatar
Rafael Ostertag committed
257
258
259
260
261
Server Response
:   The response contains at least a [Minimal Response]. In addition, a
	[Form Group Configuration Response],
	[HTML Form Element Validation Response] and/or
	[Redirection Response] may be included.
Carsten  Rose's avatar
Carsten Rose committed
262
263


Rafael Ostertag's avatar
Rafael Ostertag committed
264
### File Upload
Carsten  Rose's avatar
Carsten Rose committed
265

Rafael Ostertag's avatar
Rafael Ostertag committed
266
267
268
269
Files are uploaded asynchronously. Each file to be uploaded requires
one request to the Server, using a Multi part form with file content,
parameter `s` containing SIP, and parameter `name` containing the name
of the HTML Form Element.
Carsten  Rose's avatar
Carsten Rose committed
270

Rafael Ostertag's avatar
Rafael Ostertag committed
271
272
Request
:	api/file.php
Carsten  Rose's avatar
Carsten Rose committed
273

Rafael Ostertag's avatar
Rafael Ostertag committed
274
275
Request Method
:	POST
Carsten  Rose's avatar
Carsten Rose committed
276

Rafael Ostertag's avatar
Rafael Ostertag committed
277
278
URL Parameters
:	`action=upload`
Carsten  Rose's avatar
Carsten Rose committed
279

Rafael Ostertag's avatar
Rafael Ostertag committed
280
281
Server Response
:	The response contains a [Minimal Response].
Carsten  Rose's avatar
Carsten Rose committed
282
283


Rafael Ostertag's avatar
Rafael Ostertag committed
284
### File Delete
Carsten  Rose's avatar
Carsten Rose committed
285

Rafael Ostertag's avatar
Rafael Ostertag committed
286
287
288
289
290
291
Files are delete asynchronously. Each file to be delete on the
serverside requires on request to the Server. The parameters
identifying the file to be deleted are sent as part of the POST
body. The SIP of the request is included in the parameter name
`s`. The value of the `name` attribute of the HTML Form Element is
provided in `name`.
Carsten  Rose's avatar
Carsten Rose committed
292

Rafael Ostertag's avatar
Rafael Ostertag committed
293
294
Request
:	api/file.php
Carsten  Rose's avatar
Carsten Rose committed
295

Rafael Ostertag's avatar
Rafael Ostertag committed
296
297
Request Method
:	POST
Carsten  Rose's avatar
Carsten Rose committed
298

Rafael Ostertag's avatar
Rafael Ostertag committed
299
300
URL Parameters
:	`action=delete`
Carsten  Rose's avatar
Carsten Rose committed
301

Rafael Ostertag's avatar
Rafael Ostertag committed
302
303
Server Response
:	The response contains a [Minimal Response].
Carsten  Rose's avatar
Carsten Rose committed
304
305


306
### Record(s) delete
Carsten  Rose's avatar
Carsten Rose committed
307

308
309
Request the deletion of the record identified by the SIP. The SIP might contain a SIP_TABLE and/or a SIP_FORM.
If both are specified, SIP_FORM will be taken. With SIP_FORM, the tableName is derived from the form. 
Carsten  Rose's avatar
Carsten Rose committed
310

Rafael Ostertag's avatar
Rafael Ostertag committed
311
312
Request
:	api/delete.php
Carsten  Rose's avatar
Carsten Rose committed
313

Rafael Ostertag's avatar
Rafael Ostertag committed
314
315
Request Method
:	POST
Carsten  Rose's avatar
Carsten Rose committed
316

Rafael Ostertag's avatar
Rafael Ostertag committed
317
318
URL Parameters
:	`s=<SIP>`
Carsten  Rose's avatar
Carsten Rose committed
319

Rafael Ostertag's avatar
Rafael Ostertag committed
320
321
Server Response
:	The response contains a [Minimal Response].
322
	[Redirection Response] may be included.
Carsten  Rose's avatar
Carsten Rose committed
323
324


325
326
327
328
329
330
331
332
333
334
335
## Glossary

SIP
:   tbd

HTML Form Element
:   Any `<input>` or `<select>` HTML tag. Synonymous to *Form Element*.

Form Group
:   The sourrounding `<div>` containing the `.control-label`,
    `.form-control` `<div>`s, and `.help-block` `<p>`.
336
337

Client
338
339
340
341
342
343
344
345
346
:   Application that enables a user to interact with QFQ, i.e. a Web Browser.


Current Page
:	The currently displayed page in the Client.

Redirect
:	Issued by the Server. It is a command prompting the Client to
	navigate away from the Current Page.