PROTOCOL.md 7.23 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
### Redirection Response
137
138

Depending on the request, the server may return redirection
Rafael Ostertag's avatar
Rafael Ostertag committed
139
information to the Client. It is up to the Client to respect the
140
141
142
143
144
145
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
146
147
148
149
150
151
152
153
154
155

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

`"redirect"`
156
157
158
159
160
161
162
163
:	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
164
165


Rafael Ostertag's avatar
Rafael Ostertag committed
166
## API Endpoints
Carsten  Rose's avatar
Carsten Rose committed
167
168


Rafael Ostertag's avatar
Rafael Ostertag committed
169
### Form Update
Carsten  Rose's avatar
Carsten Rose committed
170

171
172
173
174
175
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`.
176

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

Rafael Ostertag's avatar
Rafael Ostertag committed
180
181
Request URL
:	api/load.php
Carsten  Rose's avatar
Carsten Rose committed
182

Rafael Ostertag's avatar
Rafael Ostertag committed
183
184
Request Method
:	POST
Carsten  Rose's avatar
Carsten Rose committed
185

Rafael Ostertag's avatar
Rafael Ostertag committed
186
187
URL Parameters
:	none
Carsten  Rose's avatar
Carsten Rose committed
188

Rafael Ostertag's avatar
Rafael Ostertag committed
189
190
191
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
192
193


Rafael Ostertag's avatar
Rafael Ostertag committed
194
### Form Save
Carsten  Rose's avatar
Carsten Rose committed
195

Rafael Ostertag's avatar
Rafael Ostertag committed
196
197
198
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
199

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

Rafael Ostertag's avatar
Rafael Ostertag committed
203
204
Request URL
:	api/save.php
Carsten  Rose's avatar
Carsten Rose committed
205

Rafael Ostertag's avatar
Rafael Ostertag committed
206
207
Request Method
:	POST
Carsten  Rose's avatar
Carsten Rose committed
208

Rafael Ostertag's avatar
Rafael Ostertag committed
209
210
URL Parameters
:	none
Carsten  Rose's avatar
Carsten Rose committed
211

Rafael Ostertag's avatar
Rafael Ostertag committed
212
213
214
215
216
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
217
218


Rafael Ostertag's avatar
Rafael Ostertag committed
219
### File Upload
Carsten  Rose's avatar
Carsten Rose committed
220

Rafael Ostertag's avatar
Rafael Ostertag committed
221
222
223
224
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
225

Rafael Ostertag's avatar
Rafael Ostertag committed
226
227
Request
:	api/file.php
Carsten  Rose's avatar
Carsten Rose committed
228

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

Rafael Ostertag's avatar
Rafael Ostertag committed
232
233
URL Parameters
:	`action=upload`
Carsten  Rose's avatar
Carsten Rose committed
234

Rafael Ostertag's avatar
Rafael Ostertag committed
235
236
Server Response
:	The response contains a [Minimal Response].
Carsten  Rose's avatar
Carsten Rose committed
237
238


Rafael Ostertag's avatar
Rafael Ostertag committed
239
### File Delete
Carsten  Rose's avatar
Carsten Rose committed
240

Rafael Ostertag's avatar
Rafael Ostertag committed
241
242
243
244
245
246
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
247

Rafael Ostertag's avatar
Rafael Ostertag committed
248
249
Request
:	api/file.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
:	`action=delete`
Carsten  Rose's avatar
Carsten Rose committed
256

Rafael Ostertag's avatar
Rafael Ostertag committed
257
258
Server Response
:	The response contains a [Minimal Response].
Carsten  Rose's avatar
Carsten Rose committed
259
260


Rafael Ostertag's avatar
Rafael Ostertag committed
261
### Record delete
Carsten  Rose's avatar
Carsten Rose committed
262

263
264
265
Request the deletion of the record identified by the SIP. The SIP references always the recordId SIP_
might reference a form 'SIP_FORM' (whereas a tableName is derived from) or 
reference a tableName directly 'SIP_TABLE'. 
Carsten  Rose's avatar
Carsten Rose committed
266

Rafael Ostertag's avatar
Rafael Ostertag committed
267
268
Request
:	api/delete.php
Carsten  Rose's avatar
Carsten Rose committed
269

Rafael Ostertag's avatar
Rafael Ostertag committed
270
271
Request Method
:	POST
Carsten  Rose's avatar
Carsten Rose committed
272

Rafael Ostertag's avatar
Rafael Ostertag committed
273
274
URL Parameters
:	`s=<SIP>`
Carsten  Rose's avatar
Carsten Rose committed
275

Rafael Ostertag's avatar
Rafael Ostertag committed
276
277
Server Response
:	The response contains a [Minimal Response].
Carsten  Rose's avatar
Carsten Rose committed
278
279


280
281
282
283
284
285
286
287
288
289
290
## 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>`.
291
292

Client
293
294
295
296
297
298
299
300
301
:   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.