Using HTTP GET/POST directly

Fieldpine Servers can use normal HTTP GET/POST/PUT/etc verbs rather than websockets. This can be a better choice in some circumstances, and may be simplier to work on depending on your tooling. Tools such as CURL are easier with HTTP operation, so you will typically not use a websocket in script jobs

Fieldpine servers are architected around receiving FD1 JSON packets and replying to that when ready. With a websocket, you can issue hundreds of requests over the websocket; when using HTTP, you issue hundreds of seperate GET requests.

Notes

1. The server does not really care if you use HTTP directly.
2. Documentation only shows the JSON packets, but these are easily converted to HTTP GET/POST syntax
3. You cannot use streaming functions such as firehoses. A firehose requires a persisent connection to send updates. You can of course poll periodically
4. When a non websocket request is received, such as a GET, the server converts this to a pseudo websocket and creates the JSON request. When the response is ready, it is sent and the HTTP connection closed as normal.
5. You will need to supply authorisation data in an HTTP header, rather than as the initial packet used on websockets
6. Performance wise, HTTP requests incur slightly more overhead.
   • HTTP headers are sent on every request, increasing network bandwidth.
   • The server runs security checks and validations on every request
   • There may be CORS considerations
   • The above is completely standard processing, this is not due to FD1 itself.

Trivia. The naming of FD1 endpoints was influenced by HTTP requests. While an endpoint like fd1.products.get_products would seem to make more sense as just fd1.products.get - which becomes /fd1/products/get. Browser debug consoles often only show the last part of the URL, so finding which "get" was for products vs sales, customer, etc was annoying.

Authentication

When using GET/POST, your authentication details are supplied in the header "x-apikey" (or just "apikey")

Using CURL

curl -H "x-apikey: AMKDJ34ghfg3h5hvBfh3h6" https://my-server.com/fd1/products/get_products?department=fresh

Using Javascript fetch

fetch("https://my-server.com/fd1/products/get_products?department=fresh", {
    headers: {
        "x-apikey": "AMKDJ34ghfg3h5hvBfh3h6"
    }
}).then( ... )

or, if you prefer to create a request object rather than building URLs

set request = {
    a: "fd1.products.get_products",
    q: {
        department: fresh
    }
}

fetch("https://my-server.com/fd1/products/get_products", {
    method: "POST",
    headers: {
        "x-apikey": "AMKDJ34ghfg3h5hvBfh3h6"
    },
    body: JSON.stringify(request)
}).then( ... )

fetch("https://my-server.com/"+request.a.split(".").join("/"), {
    method: "POST",
    headers: {
        "x-apikey": "AMKDJ34ghfg3h5hvBfh3h6"
    },
    body: JSON.stringify(request)
}).then( ... )