API

The SFSQL API is implemented using JSON-over-HTTP Payloads.
It is language-agnostic with no special libraries or drivers to install.
Request Payloads are submitted to SFSQL API Endpoints via HTTP POSTs.

Dependencies:
  • JSON
    Use any JSON library/interface supported by your programming language
  • HTTP
    Use any HTTP library/interface supported by your programming language
API Index:
HTTP Connection
  • Method: POST
  • URI:
    • if Self-Hosted: The host and port you specified on daemon start using the -p parameter. See SFSQL Daemon
    • else: The URI as specified by your hosting provider: Example, see demo
  • Headers:
    • Content-Type: application/json
    • x-sfsql-apikey: YOUR_APIKEY

      NOTE: if you are self-hosting you can elect to start your SFSQL daemon without specifying an apikey in which case this HTTP header would not be required.
JSON Request Payloads consist of an array of one or more Commands

Example:
A 'modify' command followed by a 'query' Command within the same Request Payload.
(NOTE: below is skeleton structure showing only the command names for clarity).
[ { "modify": ... }, { "query": ... } ]

Additionally, one or more SubCommands may be specified for a Command.

Example of a SubCommand prepended as the first element of array:
A 'modify' Command with the "#append" SubCommand specified on an array of person objects. In this example, 'Ian Redy' is appended to the array.
[ { "modify": { data: { "o:person": [ { "#append": {} }, { "s:firstname": "Ian", "s:lastname": "Redy" } ] } } } ]
Example of a SubCommand included as an object attribute.
A 'modify' Command with the "#update" SubCommand specified on a single person object. In this example the person matching the 'where' clause is updated and we add a middle name.
(#update limits modifications to pre-existing data only).
[ { "modify": { data: { "o:person": { "#update: { "where":"$lastname='Redy' and $firstname='Ian'" }, "s:middlename": "Relly" } } } } ]

See Commands for more detail.
JSON Response Payloads consist of an array of one or more Command Responses

Example Response received after sending a Request which contained a modify Command followed by a query Command.
[ { "cmdname" : "modify", "success" : 1, "_comment" : "add Person object", "result.oid" : "633159", "result.anid" : "532" }, { "cmdname" : "query", "success" : 1, "data" : [ { "oid" : 633159, "firstname" : "Sue", "lastname" : "Smith" } ], "_comment" : "select Person Object" } ]
Reflexive Parameters
  • Example:
    "_comment": "test query"
  • Returned (reflected) back within a Command Response
  • User-created
  • Can be included as Command Parameters
  • Underscore-prefixed
  • Can include parse-delimited variables to return system-generated values:
    "_newPersonOid": "!@result.oid@!"
Payload-scoped Parameters
  • All the qualities of Reflexive Parameters with the addition of being available to all other Commands within the same Request Payload
  • Example definition (within a modify command):
    "__newPersonOid": "!@result.oid@!"
  • Double-underscore-prefixed
  • Example reference (within a query command in same Request Payload:
    "sfsql": "SELECT $s:person.firstName WHERE $o:person.oid()=!@__newPersonOid@!"



See demo for complete syntax within live examples