Ocient HTTP Query API

The OcientAIQ™ Unified Data Platform provides an HTTP Query API that enables the execution of SQL statements. This page uses command-line examples using curl. The HTTP Query API returns data in JSON format by default. The default header value is Accept: application/json.

API Documentation

The API follows OpenAPI Specification (Swagger®) guidelines, which you can access in these formats from any SQL Node address {sql_node_address}:

YAML format: /openapi.yaml endpoint
JSON format: /openapi.json endpoint

YAML Download Example

CURL

curl https://{sql_node_address}/openapi.yaml

JSON Download Example

CURL

curl https://{sql_node_address}/openapi.json

You can use these specifications with various OpenAPI tools for code generation, testing, and documentation.

Connection Setup

The connectivity pool defines connection settings for SQL Nodes, including their open port and address. For details, see CONNECTIVITY POOL. A standard production install enables the OpenAPI port by default. At bootstrap, the system creates a default system connectivity pool and sets the openapi_port value of each participant to 443 + node port offset. This setting mirrors the offset that the SQL port (4050) and REST port (9090) already apply. You do not need to configure anything to reach the HTTP Query API or web UI on a fresh cluster.

All the examples assume that the openapi_port is the standard SSL port 443. If your connectivity pool openapi_port has a different port setting, you must specify it in the request URL. For example, this URL specifies using port 8443: https://sql_node_address:8443/v1/execute/.

Because 443 is a privileged port, the system applies this default value only when the rolehostd process runs as root or has the CAP_NET_BIND_SERVICE capability. Otherwise, the openapi_port remains unset, and you must configure it manually using this SQL statement. Enable or Change the OpenAPI Port To open a port on a participant that does not already have one, or to change the port from its default, execute this ALTER CONNECTIVITY POOL SQL statement. Change the connectivity pool and node values in the example according to your system.

SQL

ALTER CONNECTIVITY_POOL benchmark_sql_connectivity_pool
    ALTER PARTICIPANT "benchmark-sql0" SET openapi_port 443;

Check Port Configuration

Verify your port configuration by executing this query.

SQL

SELECT c.name, n.name, openapi_port
    FROM sys.connectivity_pool_participants AS cp
    LEFT JOIN sys.connectivity_pools AS c ON cp.id = c.id
    LEFT JOIN sys.nodes AS n ON cp.node_id = n.id;

The output displays all configured connectivity pools with their associated nodes and OpenAPI ports.

SSL Certificate Setup

The Ocient® HTTP Query API supports two options for handling SSL certificates. Secure Connection Using TLS You can use your own certificates for TLS-secured connections by configuring certificate files in your Ocient install. For details, see Secure Connections Using TLS. Unsecured Connection For quick testing or in non-production environments, you can bypass certificate validation by adding the -k or --insecure flag to your curl command. Example

SQL

curl -k -u 'admin@system:admin' https://<sql-node-address>/v1/execute/system \
    -d '{"statement":"SELECT * FROM sys.dummy2;","format":"collection"}'

Authentication Methods

The Ocient HTTP Query API accepts user credentials in various formats designed for different use cases. Simple API Requests For simple queries, you can include user credentials in the request. In this example, the request includes credentials after the -u flag.

CURL

curl -u 'admin@system:admin' https://sql_node/v1/execute/system \
    -d '{"statement":"SELECT * FROM sys.dummy2;", "format": "collection"}'

Bearer Token Authentication For continuous access, you can obtain an authentication token by making a request to the login endpoint. Replace the text in this example with the address of your SQL Node, your username, your password, and the name of your database.

CURL

curl -X POST https://sql_node/v1/login \
    -H "Content-Type: application/json" \
    -d '{
        "username": "admin@system",
        "password": "admin",
        "database": "system"
    }'

This request returns an authentication token that you can add to subsequent requests.

CURL

curl -X POST https://sql_node/v1/execute \
    -H "Authorization: Bearer TEST_ACCESS_TOKEN" \
    -H "Content-Type: application/json" \
    -d '{
        "statement": "SELECT * FROM sys.dummy2;",
        "database": "system",
        "format": "collection"
    }'

OpenID Connect (SSO) For SSO authentication, you can use OpenID Connect by targeting the sso_authentication endpoint with a callback path. Replace the text in this example with the name of your instance, the name of your database, and your callback path.

CURL

curl -X POST https://ocient-instance/v1/sso_authentication \
    -H "Content-Type: application/json" \
    -d '{
        "database": "system",
        "sso_callback_path": "/app_callback"
    }'

After the redirection and authentication are complete, you can include your token in subsequent requests.

CURL

curl -X POST https://ocient-instance/v1/sso_token \
    -H "Content-Type: application/json" \
    -d '{
        "id_token": "TEST_ID_TOKEN",
        "database": "system"
    }'

API Endpoint Documentation

The Ocient HTTP Query API supports these endpoints. For API requests, JSON data must use double quotes (") for all keys and string values. Single quotes should enclose the JSON payload, as shown in this example (see the payload section following the -d flag).

CURL

curl -X POST \
    https://my_sql_node.com/v1/execute \
    -H "Content-Type: application/json" \
    -d '{ "query": "SELECT * FROM my_table WHERE status = \"active\"", "database": "my_database" }'

Single or double quotes are acceptable for parameters not nested in JSON objects.

OcientAIQ Unified Data Platform

API Documentation

Connection Setup

Check Port Configuration

SSL Certificate Setup

Authentication Methods

API Endpoint Documentation

Endpoints

POST execute

GET execute

GET info

POST login

POST logout

POST sso_authentication

GET callback

POST sso_token

POST sso_device_grant

POST sso_device_grant_verify

POST token_refresh

​API Documentation

​Connection Setup

​Check Port Configuration

​SSL Certificate Setup

​Authentication Methods

​API Endpoint Documentation

​Endpoints

POST execute

GET execute

GET info

POST login

POST logout

POST sso_authentication

GET callback

POST sso_token

POST sso_device_grant

POST sso_device_grant_verify

POST token_refresh

​Related Links

API Documentation

Connection Setup

Check Port Configuration

SSL Certificate Setup

Authentication Methods

API Endpoint Documentation

Endpoints

Related Links