altibase/data-api repository overview

⁠Altibase DataAPI

Altibase DataAPI is a Spring Boot based HTTP service that exposes Altibase SQL execution through JSON-based HTTP APIs. It allows client applications to authenticate with database credentials or a DataAPI-issued JWT, then run SQL queries, DML/DDL statements, streaming reads, and operational monitoring requests against Altibase.

⁠Key Features

• SQL over HTTP: Execute SELECT, DML, and DDL statements through JSON-based HTTP endpoints.
• Multiple result formats: Choose row-based JSON objects, compact columns + rows payloads, or NDJSON streaming for large result sets.
• Altibase role based authorization: Use database roles such as DATA_API_ACCESS and DATA_API_MONITORING to separate SQL access from monitoring access.
• Basic and JWT authentication: Use Basic authentication for request-by-request credential validation, or use DataAPI-issued JWT access and refresh tokens for login, refresh, session reset, and logout flows.
• Streaming support: Consume large query results as application/x-ndjson without buffering the full result set in memory.
• Operational visibility: Expose Actuator health, metrics, Prometheus, and connection pool status endpoints for operations and monitoring.
• Docker friendly configuration: Configure database connection, JWT signing, API documentation, context path, and role names through environment variables.

⁠Image Tags

The default product line targets Altibase 8.

altibase/data-api:<version>

For Altibase 7 compatible deployments, use the -altibase7 tag.

altibase/data-api:<version>-altibase7

Use an explicit version tag for production deployments. The latest tag should only be used when your deployment policy accepts moving tags.

⁠Quick Start

⁠1. Requirements

• Docker Engine
• A running Altibase database server
• A database user with the required Altibase role grants
• JWT_SECRET configured with a strong HS256 signing secret

⁠2. Pull Image

docker pull altibase/data-api:<version>

For Altibase 7 compatible deployments:

docker pull altibase/data-api:<version>-altibase7

⁠3. Run Container

Bash (Linux / macOS):

docker run -d \
  --name data-api \
  -p 8080:8080 \
  -e DATAAPI_ALTIBASE_HOST=host.docker.internal \
  -e DATAAPI_ALTIBASE_PORT=20300 \
  -e DATAAPI_DBNAME=mydb \
  -e JWT_SECRET=01234567890123456789012345678901 \
  -e SWAGGER_ENABLED=true \
  -e API_DOCS_ENABLED=true \
  --add-host host.docker.internal:host-gateway \
  altibase/data-api:<version>

PowerShell (Windows):

docker run -d `
  --name data-api `
  -p 8080:8080 `
  -e DATAAPI_ALTIBASE_HOST=host.docker.internal `
  -e DATAAPI_ALTIBASE_PORT=20300 `
  -e DATAAPI_DBNAME=mydb `
  -e JWT_SECRET=01234567890123456789012345678901 `
  -e SWAGGER_ENABLED=true `
  -e API_DOCS_ENABLED=true `
  --add-host host.docker.internal:host-gateway `
  "altibase/data-api:<version>"

After startup, the default base URL is:

http://localhost:8080/dataapi

If Altibase is running on another host, replace DATAAPI_ALTIBASE_HOST with the actual database server IP address or DNS name.

⁠API Documentation

Swagger UI and OpenAPI JSON are disabled by default. Enable them with:

SWAGGER_ENABLED=true
API_DOCS_ENABLED=true

When enabled, the default documentation endpoints are:

http://localhost:8080/dataapi/swagger-ui.html
http://localhost:8080/dataapi/v3/api-docs

⁠Authentication Flow

Get a DataAPI-issued JWT token:

curl -X POST http://localhost:8080/dataapi/auth/token \
  -H "Content-Type: application/json" \
  -d '{
    "username": "app_user",
    "password": "app_password"
  }'

Run a SQL query with the access token:

curl -X POST http://localhost:8080/dataapi/query/records \
  -H "Authorization: Bearer <access-token>" \
  -H "Content-Type: application/json" \
  -d '{
    "sql": "SELECT ID, NAME FROM EMPLOYEES WHERE DEPARTMENT_ID = ?",
    "args": [10]
  }'

DataAPI issues its own JWT access and refresh tokens. Client applications must handle access token expiration by calling /auth/refresh and replacing both the access token and refresh token with the newly returned values.

⁠Input and Output Contract

SQL endpoints accept a JSON request body with a sql string and an optional args array. If args is omitted or null, DataAPI treats it as an empty array. Client applications should pass external values through ? placeholders and args so DataAPI can bind them through JDBC PreparedStatement parameters.

{
  "sql": "SELECT ID, NAME FROM EMPLOYEES WHERE DEPARTMENT_ID = ?",
  "args": [10]
}

Main response shapes:

For /execute, a one-dimensional args array is a single execution. A two-dimensional args array is treated as a JDBC batch for DML statements and is executed with an all-or-nothing transaction contract. Streaming endpoints return application/x-ndjson; clients should process the response line by line and treat the final complete line as the success signal.

Error responses use a stable JSON shape with code, message, path, timestamp, and optional details. Streaming endpoints can return this JSON error shape only before the first NDJSON line is written; after streaming starts, clients should treat a missing complete line as an incomplete stream.

⁠Common Environment Variables

⁠Notes

• Do not store database passwords, Docker Hub credentials, or JWT secrets in the image.
• Pass runtime secrets through your deployment platform, secret manager, or environment variables.
• The Altibase 8 and Altibase 7 compatible images contain different executable JAR files. Do not publish both product lines to the same immutable version tag.
• For multi-instance deployments using DataAPI-issued JWTs, route a user's JWT-based requests to the same DataAPI instance unless your deployment design externalizes the runtime session state.

⁠Manual

For complete usage instructions, see the Altibase DataAPI Manual⁠.