FD1 Client Protocol
 
Library Developer Home FD1 Client Protocol Home Concepts Reading Data Writing Data Protocol Defined Servers Connect & Authenticate Proxies & Tunnels
Webhooks Programming Support Logging Minor Facts State Facts Response Format How To Guides eCommerce Sites Custom Point of Sale Customer Access Bulk Downloads Major APIs / Endpoints All Endpoints Products Sales SalesBuilder Session Sale Capture General Purpose Data Capture Devices Barcode Scanners Eftpos IoT Sensors Power Outlets Printing Scales Security Cameras Purchasing / Supply Side Purchase Orders Invoices Invoice Payments Document Capture Rare APIs / Endpoints SSL Certificates API Key Management Diagnositics Server to Client Messages Overview Resources / Objects Purchase Order Invoice Payable Invoice Payment Product Supplier Location Sale Lines Sale Delivery Details Sales Price Maps Employees Carriers Payments Product Kits Department 1 Customers

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

NameDescripton
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.
  • "ch" or "chunk". Specifies that the response can be spread over multiple seperate reply packets if needed
  • "binary". Advises that a binary response is acceptable. Binary response is not currently publically defined.

Response Packets

NameDescripton
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

  1. Any Field name that starts with an underscore has special meaning
  2. Any field that starts with a letter is a reference to column in the data
  3. If a field name is used in isolation (eg just "id" ) then this means id=value
  4. 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 FieldServer 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
NameDescripton
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" }
        ]
    }
}