PROTOCOL.md 9.48 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"`.
	

136
### Element Configuration Response
Rafael Ostertag's avatar
Rafael Ostertag committed
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

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>"`.

178
If the element has no `"<attr_nameN>"` attribute, the attribute will be created. In any case, the attribute's value will be set 
Rafael Ostertag's avatar
Rafael Ostertag committed
179
180
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
		"redirect": "no" | "url" | "url-skip-history" | "client"
195
196
197
198
199
200
		"redirect-url": "<url>"
		...
	}
	

`"redirect"`
201
202
203
:	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
204
205
	provided in `"redirect-url"`. `"url-skip-history"` behaves like
	`"url"` but the current page will skip the browser history.
206
207
208
209
	
`"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
210

211
212
213
214
215
216
217
218
219
220
221
222
223
224
### Typeahead dict Response

    {
		...
		[
			{
				"key": "<key value>",
				"value": <display value>
			},
			...
		],
		...
    }

Carsten  Rose's avatar
Carsten Rose committed
225

Rafael Ostertag's avatar
Rafael Ostertag committed
226
## API Endpoints
Carsten  Rose's avatar
Carsten Rose committed
227
228


Rafael Ostertag's avatar
Rafael Ostertag committed
229
### Form Update
Carsten  Rose's avatar
Carsten Rose committed
230

231
232
233
234
235
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`.
236

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

Rafael Ostertag's avatar
Rafael Ostertag committed
240
241
Request URL
:	api/load.php
Carsten  Rose's avatar
Carsten Rose committed
242

Rafael Ostertag's avatar
Rafael Ostertag committed
243
244
Request Method
:	POST
Carsten  Rose's avatar
Carsten Rose committed
245

Rafael Ostertag's avatar
Rafael Ostertag committed
246
247
URL Parameters
:	none
Carsten  Rose's avatar
Carsten Rose committed
248

Rafael Ostertag's avatar
Rafael Ostertag committed
249
250
251
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
252
253


Rafael Ostertag's avatar
Rafael Ostertag committed
254
### Form Save
Carsten  Rose's avatar
Carsten Rose committed
255

Rafael Ostertag's avatar
Rafael Ostertag committed
256
257
258
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
259

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

Rafael Ostertag's avatar
Rafael Ostertag committed
263
264
Request URL
:	api/save.php
Carsten  Rose's avatar
Carsten Rose committed
265

Rafael Ostertag's avatar
Rafael Ostertag committed
266
267
Request Method
:	POST
Carsten  Rose's avatar
Carsten Rose committed
268

Rafael Ostertag's avatar
Rafael Ostertag committed
269
270
URL Parameters
:	none
Carsten  Rose's avatar
Carsten Rose committed
271

Rafael Ostertag's avatar
Rafael Ostertag committed
272
273
274
275
276
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
277
278


Rafael Ostertag's avatar
Rafael Ostertag committed
279
### File Upload
Carsten  Rose's avatar
Carsten Rose committed
280

Rafael Ostertag's avatar
Rafael Ostertag committed
281
282
283
284
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
285

Rafael Ostertag's avatar
Rafael Ostertag committed
286
287
Request
:	api/file.php
Carsten  Rose's avatar
Carsten Rose committed
288

Rafael Ostertag's avatar
Rafael Ostertag committed
289
290
Request Method
:	POST
Carsten  Rose's avatar
Carsten Rose committed
291

Rafael Ostertag's avatar
Rafael Ostertag committed
292
293
URL Parameters
:	`action=upload`
Carsten  Rose's avatar
Carsten Rose committed
294

Rafael Ostertag's avatar
Rafael Ostertag committed
295
296
Server Response
:	The response contains a [Minimal Response].
Carsten  Rose's avatar
Carsten Rose committed
297
298


Rafael Ostertag's avatar
Rafael Ostertag committed
299
### File Delete
Carsten  Rose's avatar
Carsten Rose committed
300

Rafael Ostertag's avatar
Rafael Ostertag committed
301
302
303
304
305
306
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
307

Rafael Ostertag's avatar
Rafael Ostertag committed
308
309
Request
:	api/file.php
Carsten  Rose's avatar
Carsten Rose committed
310

Rafael Ostertag's avatar
Rafael Ostertag committed
311
312
Request Method
:	POST
Carsten  Rose's avatar
Carsten Rose committed
313

Rafael Ostertag's avatar
Rafael Ostertag committed
314
315
URL Parameters
:	`action=delete`
Carsten  Rose's avatar
Carsten Rose committed
316

Rafael Ostertag's avatar
Rafael Ostertag committed
317
318
Server Response
:	The response contains a [Minimal Response].
Carsten  Rose's avatar
Carsten Rose committed
319
320


321
### Record(s) delete
Carsten  Rose's avatar
Carsten Rose committed
322

323
324
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
325

Rafael Ostertag's avatar
Rafael Ostertag committed
326
327
Request
:	api/delete.php
Carsten  Rose's avatar
Carsten Rose committed
328

Rafael Ostertag's avatar
Rafael Ostertag committed
329
330
Request Method
:	POST
Carsten  Rose's avatar
Carsten Rose committed
331

Rafael Ostertag's avatar
Rafael Ostertag committed
332
333
URL Parameters
:	`s=<SIP>`
Carsten  Rose's avatar
Carsten Rose committed
334

Rafael Ostertag's avatar
Rafael Ostertag committed
335
336
Server Response
:	The response contains a [Minimal Response].
337
	[Redirection Response] may be included.
Carsten  Rose's avatar
Carsten Rose committed
338

339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
### Typeahead

The Client initiates Typeahead actions via a GET request. A JSON key/value dict will we be send back as response.
The Client GET request contains a 'sip' and the already typed value as 'query' paramter.    

Request URL
:	api/typeahead.php

Request Method
:	GET

URL Parameters
:	`sip`, `query`

Server Response
:   The response contains at least a [Minimal Response]. In addition, a [Typeahead dict],
Carsten  Rose's avatar
Carsten Rose committed
355

356
357
358
## Glossary

SIP
359
:   Server Id Pairs 
360
361
362
363
364
365
366

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>`.
367
368

Client
369
370
371
372
373
374
375
376
377
:   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.