openapi.json

{
  "openapi": "3.0.0",
  "info": {
    "title": "SQL Query API",
    "description": "API for executing SQL queries with support for both standard and streaming responses",
    "version": "1.0.0"
  },
  "servers": [
    {
      "url": "{basePath}",
      "variables": { "basePath": { "description": "Base URL of the API" } }
    }
  ],
  "paths": {
    "/query/raw": {
      "post": {
        "summary": "Execute SQL queries",
        "description": "Execute a single SQL query or multiple queries in a transaction. Returns results in standard or streaming format based on Accept header.",
        "security": [
          {
            "BearerAuth": []
          },
          {
            "BasicAuth": []
          }
        ],
        "parameters": [
          {
            "name": "Accept",
            "in": "header",
            "description": "Response format (application/json for standard response, application/x-ndjson for streaming)",
            "required": false,
            "schema": {
              "type": "string",
              "enum": ["application/json", "application/x-ndjson"],
              "default": "application/json"
            }
          }
        ],
        "requestBody": {
          "description": "Query or transaction to execute",
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "oneOf": [
                  {
                    "type": "object",
                    "properties": {
                      "sql": {
                        "type": "string",
                        "description": "SQL query to execute"
                      },
                      "params": {
                        "type": "array",
                        "items": {
                          "oneOf": [
                            { "type": "string" },
                            { "type": "number" },
                            { "type": "boolean" },
                            { "type": "null" }
                          ]
                        },
                        "description": "Optional array of parameter values"
                      }
                    },
                    "required": ["sql"]
                  },
                  {
                    "type": "object",
                    "properties": {
                      "transaction": {
                        "type": "array",
                        "items": {
                          "type": "object",
                          "properties": {
                            "sql": {
                              "type": "string",
                              "description": "SQL query to execute"
                            },
                            "params": {
                              "type": "array",
                              "items": {
                                "oneOf": [
                                  { "type": "string" },
                                  { "type": "number" },
                                  { "type": "boolean" },
                                  { "type": "null" }
                                ]
                              },
                              "description": "Optional array of parameter values"
                            }
                          },
                          "required": ["sql"]
                        },
                        "description": "Array of queries to execute in a transaction"
                      }
                    },
                    "required": ["transaction"]
                  }
                ]
              },
              "examples": {
                "singleQuery": {
                  "value": {
                    "sql": "SELECT * FROM users WHERE age > ?",
                    "params": [21]
                  }
                },
                "transaction": {
                  "value": {
                    "transaction": [
                      {
                        "sql": "INSERT INTO users (name, age) VALUES (?, ?)",
                        "params": ["John Doe", 30]
                      },
                      {
                        "sql": "SELECT * FROM users WHERE name = ?",
                        "params": ["John Doe"]
                      }
                    ]
                  }
                }
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Query executed successfully",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "result": {
                      "type": "array",
                      "items": {
                        "type": "object",
                        "properties": {
                          "columns": {
                            "type": "array",
                            "items": {
                              "type": "string"
                            },
                            "description": "Array of column names"
                          },
                          "rows": {
                            "type": "array",
                            "items": {
                              "type": "array",
                              "items": {}
                            },
                            "description": "Array of rows, where each row is an array of values"
                          },
                          "meta": {
                            "type": "object",
                            "properties": {
                              "rows_read": {
                                "type": "integer",
                                "description": "Number of rows read by the query"
                              },
                              "rows_written": {
                                "type": "integer",
                                "description": "Number of rows written by the query"
                              }
                            },
                            "required": ["rows_read", "rows_written"]
                          }
                        },
                        "required": ["columns", "rows", "meta"]
                      },
                      "description": "Array of query results (one per query in a transaction, or a single item for a simple query)"
                    },
                    "error": {
                      "type": "string",
                      "nullable": true,
                      "description": "Error message if an error occurred, null otherwise"
                    }
                  },
                  "required": ["result"]
                },
                "example": {
                  "result": [
                    {
                      "columns": ["id", "name", "age"],
                      "rows": [
                        [1, "John Doe", 30],
                        [2, "Jane Smith", 25]
                      ],
                      "meta": {
                        "rows_read": 2,
                        "rows_written": 0
                      }
                    }
                  ],
                  "error": null
                }
              },
              "application/x-ndjson": {
                "schema": {
                  "description": "StreamRecord (new-line delimited JSON strings)",
                  "oneOf": [
                    {
                      "type": "object",
                      "properties": {
                        "type": {
                          "type": "string",
                          "enum": ["columns"],
                          "description": "Indicates this record contains column names"
                        },
                        "data": {
                          "type": "array",
                          "items": {
                            "type": "string"
                          },
                          "description": "Array of column names"
                        }
                      },
                      "required": ["type", "data"]
                    },
                    {
                      "type": "object",
                      "properties": {
                        "type": {
                          "type": "string",
                          "enum": ["row"],
                          "description": "Indicates this record contains a single row of data"
                        },
                        "data": {
                          "type": "array",
                          "items": {},
                          "description": "Array of values in the row"
                        }
                      },
                      "required": ["type", "data"]
                    },
                    {
                      "type": "object",
                      "properties": {
                        "type": {
                          "type": "string",
                          "enum": ["meta"],
                          "description": "Indicates this record contains metadata about the query"
                        },
                        "data": {
                          "type": "object",
                          "properties": {
                            "rows_read": {
                              "type": "integer",
                              "description": "Number of rows read by the query"
                            },
                            "rows_written": {
                              "type": "integer",
                              "description": "Number of rows written by the query"
                            }
                          },
                          "required": ["rows_read", "rows_written"]
                        }
                      },
                      "required": ["type", "data"]
                    },
                    {
                      "type": "object",
                      "properties": {
                        "type": {
                          "type": "string",
                          "enum": ["error"],
                          "description": "Indicates an error occurred during streaming"
                        },
                        "error": {
                          "type": "string",
                          "description": "Error message"
                        }
                      },
                      "required": ["type", "error"]
                    }
                  ]
                },
                "example": "{\"type\":\"columns\",\"data\":[\"id\",\"name\",\"age\"]}\n{\"type\":\"row\",\"data\":[1,\"John\",30]}\n{\"type\":\"row\",\"data\":[2,\"Alice\",25]}\n{\"type\":\"meta\",\"data\":{\"rows_read\":2,\"rows_written\":0}}"
              }
            }
          },
          "400": {
            "description": "Bad request due to invalid SQL or parameters",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "result": {
                      "type": "null",
                      "description": "Will be null in case of an error"
                    },
                    "error": {
                      "type": "string",
                      "description": "Error message describing what went wrong"
                    }
                  },
                  "required": ["error"]
                }
              }
            }
          },
          "401": {
            "description": "Unauthorized access",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "result": {
                      "type": "null"
                    },
                    "error": {
                      "type": "string",
                      "description": "Error message describing what went wrong"
                    }
                  },
                  "required": ["error"]
                }
              }
            }
          },
          "500": {
            "description": "Server error",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "result": {
                      "type": "null"
                    },
                    "error": {
                      "type": "string",
                      "description": "Error message describing what went wrong"
                    }
                  },
                  "required": ["error"]
                }
              }
            }
          }
        }
      },
      "options": {
        "summary": "CORS preflight request",
        "description": "Handles CORS preflight requests for the /query/raw endpoint",
        "responses": {
          "204": {
            "description": "CORS headers returned successfully",
            "headers": {
              "Access-Control-Allow-Origin": {
                "schema": {
                  "type": "string"
                },
                "example": "*"
              },
              "Access-Control-Allow-Methods": {
                "schema": {
                  "type": "string"
                },
                "example": "GET, POST, OPTIONS"
              },
              "Access-Control-Allow-Headers": {
                "schema": {
                  "type": "string"
                },
                "example": "Authorization, Content-Type, Accept, X-Starbase-Source, X-Data-Source"
              },
              "Access-Control-Max-Age": {
                "schema": {
                  "type": "string"
                },
                "example": "86400"
              }
            }
          }
        }
      }
    }
  },
  "components": {
    "securitySchemes": {
      "BearerAuth": {
        "type": "http",
        "scheme": "bearer",
        "description": "Bearer token authentication using the secret configured in middleware options"
      },
      "BasicAuth": {
        "type": "http",
        "scheme": "basic",
        "description": "Basic authentication with username and password"
      }
    }
  }
}