Commit 61abdb25 authored by Rafael Ostertag's avatar Rafael Ostertag
Browse files

Renamed API.md to PROTOCOL.md

parent 924b682b
<!-- -*- markdown -*- -->
API: Client / Server
====================
# Client/Server Protocol
## Form initial call
Form initial call
-----------------
Request: index.php (QuickFormQuery.php, included by Typo3 extension)
......@@ -16,22 +14,56 @@ data-hidden: 'yes'|'no' - yes: The element is not visible yet, maybe later.
data-disabled: 'yes'|'no' - yes: The element is visible, but the user can't interact with it.
data-required: 'yes'|'no' - yes: The element is required. The form can't be submitted if any required element is empty.
## General
## General Protocol
Asynchronous request (read AJAX) initiated by the client receive a JSON Response from the server containing at least:
###
Asynchronous request (read AJAX) initiated by the Client receive a
JSON Response from the server containing at least:
{
"status": "success"|"error",
"message": "<message>"
}
`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.
`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.
Depending on the request, the server may provide additional
information in the response, as outlined below.
### HTML Form Element Validation
The Server may perform a serverside validation of values submitted. If
the validation fails, it may notify the Client by adding following
name/value pairs to the response JSON Stream
{
"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
the Client is expected to treat the error as explained in [General]
and must obey the rules of redirection as explained in [Redirection].
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.
### Form Group Configuration
......@@ -100,9 +132,13 @@ structure
### Redirection
Depending on the request, the server may return redirection
information to client. It is up to the client to respect the
redirection information. The format of redirect information is
outlined below
information to Client. It is up to the Client to respect the
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
{
...
......@@ -113,74 +149,38 @@ outlined below
`"redirect"`
: 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"`.
Form load (update)
------------------
### Trigger
## Form Update
Form Element with attribute `data-load="data-load"`.
Request URL
: api/load.php
The client side JavaScript installs on change handlers for all HTML Form Elements having the `data-load` attribute.
### Request: api/load.php
#### Type
POST
Request Method
: POST
#### Parameters
URL Parameters
: none
##### URL
none
Server Response
: The response contains
##### POST
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`.
HTML Form without `<input>` elements of type `file`. The HTML Form is
required to have a HTML Form Element named `s`, which must contain the
SIP.
### Response
JSON Stream
{
"status": "success"|"error",
"message": "<message>",
"redirect": "client"|"url"|"no",
"field-name": "<field name>",
"field-message": "<message>",
"form-update": [
{
"form-element": "<element_name>",
"hidden": true | false,
"disabled": true | false,
"required": true | false,
"value": <value>
}
]
}
status
: see [General]
message
: see [General]
redirect
: not used
field-name
: HTML Form Element Name which raised error on server side. Requires
status to be `"error"`
field-message
: reason of error. Requires status to be `"error"`.
form-update
: Array of Objects. Each object describes the state and value of a
HTML Form Element identfied by its `name` attribute.
The Client must include the SIP using an HTML Input Element (most likely of `type` `hidden`).
Form save
......@@ -314,4 +314,12 @@ Form Group
`.form-control` `<div>`s, and `.help-block` `<p>`.
Client
:
: 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.
Supports Markdown
0% or .
You are about to add 0 people to the discussion. Proceed with caution.
Finish editing this message first!
Please register or to comment