API Reference (beta)
The holistic.dev API is organized around REST with JSON request and responses and uses standard HTTP response codes.
The current API status is BETA. Minor changes are possible before leaving this status. After fixing the state, JSON-schemas will be published, with a description of the formats of requests and responses
Authentication
The holistic.dev API uses API key to authenticate requests. You can view and manage your API key in the Account Settings.
The holistic.dev APIs is a REST-based service. Subsequently, all requests to the APIs require this HTTP header:
x-api-key: Your API keyContent type
The holistic.dev APIs is also a JSON-based service. You have to add Content-Type HTTP header to all your requests:
Content-Type: application/jsonURL and API versioning
Only one API version is operating at this time. Use this base URL for your requests:
https://api.holistic.dev/api/v1
Responses
All responses are JSON-based and follow one of these formats:
// successful response
{
"status": "OK",
"data": {...}
}
}Http codes and error message you can find at Errors section
Projects
The project represents one database. Each project has a name and database type. Each project can contain multiple environments (development, test, stage, production) and various version control system branches.
Multiple environment and multiple branches will be avalible soon.
Create project
project
POST https://api.holistic.dev/api/v1/project
Create new project
Headers
x-api-key
string
your api key
Request Body
project.name
string
project name (case insensitive)
project.db
string
"pg" only
Example:
Rename project
project
PATCH https://api.holistic.dev/api/v1/project
Rename project
Headers
x-api-key
string
your api key
Request Body
project.name
string
project new name (case insensitive)
project.uuid
string
existing project UUID
Example:
List projects
project
GET https://api.holistic.dev/api/v1/project
Get projects list
Headers
x-api-key
string
your api key
Example:
Project details
project/:uuid/details
GET https://api.holistic.dev/api/v1/project/:uuid/details
Get projects list
Path Parameters
uuid
string
project uuid
Headers
x-api-key
string
your api key
Example:
Project DDL details
project/:uuid/ddl
GET https://api.holistic.dev/api/v1/project/:uuid/ddl
Get projects list
Path Parameters
uuid
string
project uuid
Headers
x-api-key
string
your api key
Example:
Project DMLs list
project/:uuid/dml/list
GET https://api.holistic.dev/api/v1/project/:uuid/dml/list
Get projects list
Path Parameters
uuid
string
project uuid
Headers
x-api-key
string
your api key
Example:
SQL Syntax
At this time, holistic.dev support only PostgreSQL syntax. We have implemented the last original parser from PostgreSQL 13. So, we support modernist PostgreSQL features. PostgreSQL's syntax includes all standard SQL syntax, so, quite possibly, you can parse queries written for other RDBMS - Mysql, MSSQL, ORACLE, and more. But all analyzer rules aim to find specific PostgreSQL behavior.
DDL can contain multiple files. Each of them can include a lot of DDL statements. All unknown or syntactically incorrect statements will be ignored.
DML can contain only one DML statement. All other statements will be ignored. DML can contain one of the following parameter syntaxes:
Warning!
Parameter as question mark not supported!
Database schema (DDL)
DDL, aka Data Definition Language, is an SQL subset that includes CREATE, ALTER, and DROP statements. It uses to define database structure. Also, can include DML statements with extension's commands like create_hypertable() from TimescaleDB. All supported extensions you can find in the extensions list. Knowledge about database structure is the critical requirement for SQL-queries static analysis. We require to upload the database structure described in DDL syntax before process any DML queries.
Extract DDL from database
If you store database schema in your version control system, you can directly upload it for any project.
In case you have not DDL synchronized with production database in your version control system, you should extract DDL directly from target database:
database parameters:
<pg-password>
<pg-host>
<pg-port>
<pg-username>
<pg-db-name>
pg_dump utility knows nothing about extension's necessary routines. E.g., commands like create_hypertable() from TimescaleDB you should add by yourself. We recommend storing it in a separate file and upload both.
Upload DDL
ddl
POST https://api.holistic.dev/api/v1/ddl
Upload brand new ddl or replace existing ddl with new version
Headers
x-api-key
string
your api key
Request Body
project.name
string
project name (case insensitive)
ddl.version
string
any string version for history navigate (case insensitive, can be null)
files
array
array of objects { "name": "<filename:string>", "source": "<sql-source:string>" } <sql-source:string> is base64 encoded or not
Example:
base64 argument -w0 need to prevent formatting result at Linux-based os
All files of the previous version will be replaced, even if their number does not match the number of files of the new version.
Also, you can copy bash script with credentials from project card from project list inside client area: