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.

At the top level, FD1 field names are short and terse, this is to reduce network traffic and parsing overhead.

Command or Request Packets

Response Packets

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 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

{
    a: "FD1 endpoint to read products"
    q: {
        "description(like)": "en",
        "depid(in)": [3,4,5],
        "price(ge)": 100,
        "price(lt)": 2500
    }
}

Examples

{
    a: "FD1 endpoint"
}

{
    a: "FD1 endpoint to read products"
    q: {
        description: "Pencil"
    }
}

{
    a: "FD1 endpoint to read products",
    q: {
        theDescription: "Pencil"
    }
}

{
    r: "FD1 endpoint to read products",
    error: {
        message: "Query field theDescription is unknown"
    }
}

{
    a: "FD1 endpoint to read products",
    rq: 823,
    q: {
        theDescription: "Pencil"
    }
}

{
    rp: 823,
    error: {
        message: "Query field theDescription is unknown"
    }
}

{
    a: "FD1 endpoint to edit products"
    v: {
        pid: 1234,
        description: "Big pencil"
    }
}

{
    a: "FD1 endpoint to read products"
    rq: 1234,
    mo: "chunk"
}

{
    rp: 1234,
    ch: 1,
    data {
        rows: [
            { pid: 123, description: "Pencil"},
            { pid: 1234, description: "Big Pencil"},
            ...
        ]
    }
}

{
    rp: 1234,
    ch: 2,
    data {
        rows: [
            { pid: 5678, description: "Paper A4"},
            { pid: 5679, description: "Paper A4 gold"},
            ...
        ]
    }
}

{
    rp: 1234,
    ch: 0
    data {
        rows: [
            { pid: 441123, description: "Plastic plant pot"}
        ]
    }
}

{
    a: "FD1 endpoint to read products",
    rt: "iframe.48484.bksl2",
    rq: "nb87374gb",
    q: {
        pid: 456
    }
}

{
    rt: "iframe.48484.bksl2",
    rp: "nb87374gb",
    data: {
        rows: [
            { pid:456, description: "Roast beef sandwich" }
        ]
    }
}

Binary Packets

Websockets can send either text packets or binary packets. Binary packets are used for things such as images or external files, and also to transfer very large amounts of data in pieces.

When binary data is received, the first byte contains a packet content descriptor

0x01 - BinJson

This format is used to transfer relatively simple binary data, such as an image. The format is

Within the contained JSON, field names may have a |bin suffix to indicate they reference binary data. The struture is
"Field-name|bin": "binary-offset|length"

• binary-offset is relative to the start of the packet
• length is required. You will not receive binary-offset without a length
• Offset/Length may overlap with other fields using binary data, although this should be rare
• Binary data can only reference the binary section and not over or underflow
  • binary-offset must be >= 5
  • binary-offset must be < JsonOffset
  • length must be >= 0
  • (binary-offset + length) must be < JsonOffset

Example

{
    "r": "fd1.images.get_image",
    "rq": "1234",
    "data": {
        "attribution":"Photo by ....",
        "copyright":"Public domain",
        "format":"jpeg",
        "content|bin":"5|189354"
    }
}

• No binary data chunks being present is specifically allowed.
• Endpoints will document if they might respond with BinJson, you will not suddenly starting receiving these.

Protocol Type: "socket"

Packets can be sent and received over the websocket with a "pt=socket" present. This indicates the packet is not an end user FD1 packet, but rather a system link level control packet.

{
 pt: "socket",
 a: "fd1.socket.socket_option",
 ...
}

Reconnecting a Socket

Send this command first when a socket is opened to reuse a previous session. All logins and definitions are restored.

{
 pt: "socket",
 a: "fd1.socket.socket_option",
 reconnect: "...socket uniqueid provided to original socket..."
}

• Only one network connection can be connected to a socket-unique-id at a time. You cannot reconnect to a socket that is still in use.
• Reconnections can time out, dont expect to reconnect 3 days later. The actual time frame available depends on server load and volume of traffic.
• Reconnects can only be made to the same server, you cannot reconnect to a fail over server.
• You don't have to reconnect, you can simply send your login information again if you need to reopen a socket that disconnected.
• When you reconnect, and data queued will be delivered

Operational Flow

When a socket is originally opened

GET /fd1/open_websocket

{
  pt: "socket",
  data: {
    socketid: "abcdef12345",
    pid: 165348
  }
}

var SavedSocketId = event.data.data.socketid;

GET /fd1/open_websocket
{
  pt: "socket",
  a: "fd1.socket.socket_option",
  reconnect: SavedSocketId
}

Requesting Debug Mode

Instructs the server to place the socket into debug mode. The field "setdebug" contains keywords to select various debug modes.

{
  pt: "socket",
  a: "fd1.socket.socket_option",
  setdebug: "go-slow"
}