SubZero C Shared Library Documentation

Introduction

This library provides the low level C API for the SubZero. It's intended to be used by other languages to interface with the SubZero library.

The purpose of this library is to take an HTTP request and return a SQL statement that can be used to query a database and return the fully formed response body.

The HTTP request needs to conform to the SubZero HTTP request format (PostgREST compatible).

Usage

Here's a brief example on how to use the SubZero library:

// include the header file
#include "subzero.h"
// ... other includes
 
const char* db_type = "sqlite";
// Constructing the JSON schema is tedious and for this reason we provide "introspection queries"
// for each database type that can be used to generate the schema JSON automatically
const char* db_schema_json = ""
"{"
"    \"schemas\": ["
"        {"
"            \"name\": \"public\","
"            \"objects\": ["
"                {"
"                    \"kind\": \"table\","
"                    \"name\": \"clients\","
"                    \"columns\": ["
"                        {"
"                            \"name\": \"id\","
"                            \"data_type\": \"INTEGER\","
"                            \"primary_key\": true"
"                        },"
"                        {"
"                            \"name\": \"name\","
"                            \"data_type\": \"TEXT\","
"                            \"primary_key\": false"
"                        }"
"                    ],"
"                    \"foreign_keys\": []"
"                }"
"            ]"
"        }"
"    ]"
"}"
;
 
// main function
int main() {
  sbz_DbSchema* db_schema = sbz_db_schema_new(db_type, db_schema_json, NULL);
  if (db_schema == NULL) {
    const int err_len = sbz_last_error_length();
    char* err = (char*)malloc(err_len);
    sbz_last_error_message(err, err_len);
    printf("Error: %s\n", err);
    free(err);
    return -1;
  }
  
  const char* headers[] = {"Content-Type", "application/json", "Accept", "application/json"};
  const char* env[] = {"user_id", "1"};
  sbz_HTTPRequest* req = sbz_http_request_new(
     "GET",
     "http://localhost/rest/projects?select=id,name",
     NULL,
     headers, 4,
     env, 2
  );
  sbz_Statement* stmt = sbz_statement_new(
    "public",
    "/rest/",
    "user",
    db_schema,
    req,
    NULL
  );
 
  if (stmt == NULL) {
    const int err_len = sbz_last_error_length();
    char* err = (char*)malloc(err_len);
    sbz_last_error_message(err, err_len);
    printf("Error: %s\n", err);
    free(err);
    return -1;
  }
  
  const char* sql = sbz_statement_sql(stmt);
  const char *const * params = sbz_statement_params(stmt);
  const char *const * params_types = sbz_statement_params_types(stmt);
  int params_count = sbz_statement_params_count(stmt);
  printf("SQL: %s\n", sql);
  printf("params: %s\n", params[0]);
  printf("params_count: %d\n", params_count);
  printf("params_types: %s\n", params_types[0]);
  
  sbz_statement_free(stmt);
  sbz_http_request_free(req);
  sbz_db_schema_free(db_schema);
  return 0;
}

For more information, navigate to the Files section.