HTTP API

These are all the requests supported by Seafowl's HTTP API.

Query result format

Seafowl returns query results in the HTTP response body using the JSON Lines format, with one line per row:

{"text_column":"VALUE 1","float_column":12.34,"int_column":12}
{"text_column":"VALUE 2","float_column":56.78,"int_column":13}
{"text_column":"VALUE 3","float_column":91.01,"int_column":14}

It currently doesn't return any other (like type) information or support other return formats.

Authorization

For the purposes of authorization, Seafowl distinguishes between read-only (SELECT) and write (all other statements) SQL queries. By default, write queries require authorization and read-only don't.

Where authorization is required, it is performed by passing an Authorization: Bearer (password) HTTP header.

You can change the authorization settings in the configuration.

Endpoints

POST /q

Execute a read/write query.

Body: {"query": "(SQL query)"}

Headers:

• Authorization: Bearer (password): if authorization is required
• Content-Type: application/json: required

Returns:

• 200 OK: if the query is successful
• 400 Bad Request: error executing or planning the query, with the reason in the response body
• 401 Unauthorized: no or invalid password
• 403 Forbidden: tried to write as an anonymous user or using a read-only password

GET /q/(query_sha)[.extension]

Conditionally execute a read-only (SELECT) query if its result has changed.

• query_sha: SHA-256 hash of the query. Required.
• extension: Optional extension, like .csv. Ignored.

Headers:

• X-Seafowl-Query: The actual query. Must match the SHA-256 hash after decoded with decodeURIComponent(). Either this header or the GET request body are required.
• If-None-Match: ETag denoting the query result cached by the client. Optional.

Body: {"query": "(SQL query)"}. Must match the SHA-256 hash. Either the request body or the X-Seafowl-Query header are required.

This endpoint does not support the authorization header. If Seafowl is set up to require authorization for read-only queries, this endpoint will be disabled.

Returns:

• 200 OK: If no ETag has been passed or the passed ETag doesn't match the current ETag, generated from the latest versions of all tables involved in the query: the query result with a header ETag: [current ETag].
• 301 Not Modified response: if the ETag matches the current version.
• 400 Bad Request: error executing or planning the query, with the reason in the response body, or a mismatch between the query SHA and the SHA of the query body
• 401 Unauthorized: cached read-only endpoint is disabled because reads require a password

POST /upload/(schema_name)/(table_name)

Upload a CSV/Parquet file to a certain table. If the table already exists, attempt to insert the new data, if the schemas match.

Body: A multipart/form-data body with the following attributes:

• schema: Optional. Instead of Seafowl inferring the schema automatically, allows the user to provide an explicit JSON representation of the Arrow columnar data. Applicable only for CSV uploads.
• has_headers: Optional. Whether an explicit schema is passed through schema or one is being referred, by default it is assumed that the headers are present, to denote otherwise set to false (has_headers=false). Applicable only for CSV uploads.
• data: the file that's being uploaded

Headers:

• Authorization: Bearer (password): if authorization is required

Returns:

• 200 OK: successful upload
• 400 Bad Request: missing or invalid body or schema
• 401 Unauthorized: no or invalid password
• 403 Forbidden: tried to write as an anonymous user or using a read-only password

OPTIONS (any URL)

CORS pre-flight request (see the MDN).

Response headers:

• Access-Control-Allow-Origin: same value as the inbound Origin header
• Access-Control-Allow-Methods: GET, POST
• Access-Control-Allow-Headers: X-Seafowl-Query, Authorization, Content-Type