Webhooks
FD1 Client Protocol Definition
FD1 is a bidirectional protocol. Requests/Commands are sent and responses are received. Multiple responses are possible depending on the request.
Command or Request Packets
Name | Descripton |
a | Address or name of the endpoint this packet is intended for. |
q | "query" arguments used to select or subset an endpoint. The endpoint "list products" would use the "q" argument to select only those matching "abc" |
k | "key" provides a single value for functions that deal with single records. |
v | "values". Endpoint specific data to exchange |
rq | Request Id. A optional unique value you supply that is returned in responses. While optional, it is typically required to correctly route responses. The value you supply and be any value that can be converted to a string. It must be less than 200 characters |
rt | Requesting tab/thread. Any value sent in the request packet is reflected in the response. This allows a single web socket to be shared over multiple browser tabs or application threads. |
mo |
Mode. Sets specific mode options. The value can either an a comma seperated string or a JSON array.
|
Response Packets
Name | Descripton |
r | Reply from an endpoint. Basically your "a" reflected back. This field may not be present if you sent an "rq" in your request. |
rp | Request id that was present in the command/request packet |
rt | Request tab/thread that was present in the command/request packet. The request "rt" value supplied is returned in the response |
data | The object containing the requested data |
data.rows | An array of result rows. The result is always an array, even if zero or one result rows are returned. |
schema | What type of data is contained in "data". This value is not always present, but typically will be sent if a request can return multiple different pieces of data. |
error | |
ch |
Chunk number. When a request allows chunked response mode ( mo:'ch' ), this response field contains a number, starting at 1 for
the first packet and increasing by one (1,2,3...) for subsequent packets. The final packet is numbered 0. If the response only requies a single
packet it will be numbered 0. Should the server get it wrong and realise that the final packet has already been sent as a numbered packet, it will
send a final empty style response numbered 0.
Chunk numbers are indications only, you cannot request a single chunk to be retransmitted. |
ce | Event response number. Not yet documented. |
q "Query" Object
Some endpoints use a "q" object to query, select or restrict the data to be accessed. In SQL terminology this would be the "where" clause
- Any Field name that starts with an underscore has special meaning
- Any field that starts with a letter is a reference to column in the data
- If a field name is used in isolation (eg just "id" ) then this means id=value
-
If a field name includes a bracket reference at the end, (eg "id(gt)" ) then this defines the requested predicate check. Endpoints can block predicate types,
do not assume that you can use different predicates on every field
Q Field Server Operation field
field(=)
field(eq)
field(equal)Field = value field(>)
field(gt)
field(greaterthan)Field > value field(>=)
field(ge)
field(greaterthanequal)Field >= value field(<)
field(gt)
field(lessthan)Field < value field(<=)
field(le)
field(lessthanequal)Field <= value field(!=)
field(<>)
field(ne)
field(notequal)Field <> value field(like) Field like value
Example selecting a subset of products
{ a: "FD1 endpoint to read products" q: { "description(like)": "en", "depid(in)": [3,4,5], "price(ge)": 100, "price(lt)": 2500 } }The server might run the equivalent of this SQL
select ... where description like '%en%' and depid in (3,4,5) and price >= 100 and price < 2500
Name | Descripton |
Reply from an endpoint. Basically your "a" reflected back. This field may not be present if you sent an "rq" in your request. |
Examples
The minimum packet consists of a "a" value targeting an endpoint.
{ a: "FD1 endpoint" }
A packet requesting a subset of products
{ a: "FD1 endpoint to read products" q: { description: "Pencil" } }
A malformed packet
{ a: "FD1 endpoint to read products", q: { theDescription: "Pencil" } }
{ r: "FD1 endpoint to read products", error: { message: "Query field theDescription is unknown" } }
A malformed packet which uses a unique request id.
{ a: "FD1 endpoint to read products", rq: 823, q: { theDescription: "Pencil" } }
{ rp: 823, error: { message: "Query field theDescription is unknown" } }
A packet submitting an edit
{ a: "FD1 endpoint to edit products" v: { pid: 1234, description: "Big pencil" } }
A packet requesting all products
{ a: "FD1 endpoint to read products" rq: 1234, mo: "chunk" }
First response packet, indicated by ch=1
{ rp: 1234, ch: 1, data { rows: [ { pid: 123, description: "Pencil"}, { pid: 1234, description: "Big Pencil"}, ... ] } }
Subsequent response packets, indicated by ch=2. Each subsequent response increments this value
{ rp: 1234, ch: 2, data { rows: [ { pid: 5678, description: "Paper A4"}, { pid: 5679, description: "Paper A4 gold"}, ... ] } }
Final response packet. Field ch=0 to indicate final response
{ rp: 1234, ch: 0 data { rows: [ { pid: 441123, description: "Plastic plant pot"} ] } }
A tab specific request and response
{ a: "FD1 endpoint to read products", rt: "iframe.48484.bksl2", rq: "nb87374gb", q: { pid: 456 } }
Response
{ rt: "iframe.48484.bksl2", rp: "nb87374gb", data: { rows: [ { pid:456, description: "Roast beef sandwich" } ] } }