Agdb API

agdb API Skill

Use this skill when:

• Understanding agdb server API structure and endpoints
• Writing tests for agdb_server routes
• Explaining API behavior to implement in client libraries
• Planning API client generators or transpilations
• Debugging authentication/authorization flows
• Building wrappers or SDKs for other languages
• Interacting with the server programmatically (always use the Rust SDK, never raw JSON)

Primary sources in this repository:

• agdb_api/src/client.rs — Rust API client (all endpoint methods)
• agdb_server/openapi.json — OpenAPI 3.1.0 specification (complete contract)
• agdb_server/src/routes/ — Route implementations (auth, validation, errors)
• agdb_server/tests/ — Integration tests
• agdb_api/src/ — Rust client source package
• agdb_api/typescript/ — TypeScript client package
• agdb_api/php/ — PHP client package

API organization

The agdb server exposes a REST API at /api/v1 (or {basepath}/api/v1 when basepath is configured) organized into four endpoint families:

Admin routes (/api/v1/admin/...)

Require admin authentication. Manage all databases, users, and server state.

• Database management: /admin/db/{owner}/{db}/...

  • POST /add — Create database (body: DbKind — Memory, Mapped, File)
  • GET /audit — View database audit log → DbAudit
  • POST /backup — Create backup snapshot
  • POST /clear — Clear resources (body: ClearAudit | ClearBackup | ClearAll)
  • POST /convert — Change storage type (body: DbKind)
  • POST /copy — Copy database (body: {new_name})
  • DELETE /delete — Permanently delete database and files
  • POST /optimize — Defragment storage, returns ServerDatabase with new size
  • POST /optimize_shrink_to_fit — Defragment and shrink file on disk
  • DELETE /remove — Disassociate from server (keep data files)
  • POST /rename — Rename/move database (body: {new_name})
  • POST /restore — Restore from backup
  • POST /rollback — Rollback to previous WAL checkpoint
  • POST /exec — Execute immutable queries → Vec<QueryResult>
  • POST /exec_mut — Execute mutable queries → Vec<QueryResult>
  • GET /user/list — List database users → Vec<DbUser>
  • PUT /user/{username}/add — Add database user (body: DbUserRole)
  • DELETE /user/{username}/remove — Remove database user

• User management: /admin/user/...

  • POST /{username}/add — Create user (body: {password})
  • PUT /{username}/change_password — Change password (body: {password})
  • GET /list — List all users and sessions → Vec<UserStatus>
  • POST /{username}/logout — Logout user (all sessions on this node)
  • POST /{username}/logout?session={session} — Logout specific session
  • POST /logout_all — Logout all users on this node
  • DELETE /{username}/delete — Delete user and all owned databases

• Server management: /admin/...

  • POST /shutdown — Graceful server shutdown
  • POST /set_log_level?new_level={level} — Set log level (trace, debug, info, warn, error, off)
  • GET /status — Server status and metrics → AdminStatus

User routes (/api/v1/user/...)

Require user authentication. User manages own account.

• POST /login — Authenticate → token string (body: {username, password})
• POST /logout — Logout current session
• POST /logout?session=others — Logout all other sessions
• POST /logout?session=all — Logout all sessions
• POST /logout?session={session} — Logout specific session by id
• PUT /change_password — Change own password (body: {password})
• GET /status — Own status and sessions → UserStatus

Database routes (/api/v1/db/{owner}/{db}/...)

Require user authentication and appropriate role.

Same structure as admin database routes but scoped to owner/accessible databases:

Additionally:

• POST /add — Create database (owner must be self)
• DELETE /delete — Delete (owner only)
• DELETE /remove — Remove (owner only)
• POST /rename — Rename (owner only)
• POST /copy — Copy (owner scope)
• GET /list — List accessible databases → Vec<ServerDatabase> (no {owner}/{db} path params)

Cluster routes (/api/v1/cluster/...)

Propagate operations across all cluster nodes. These endpoints replicate the action to every node via the Raft log.

• POST /user/login — Authenticate cluster-wide → token valid on all nodes
• POST /user/logout — Logout cluster-wide
• POST /user/logout?session=others|all|{id} — Logout variants across cluster
• POST /admin/user/{username}/logout — Admin logout user across cluster
• POST /admin/user/{username}/logout?session={session} — Admin logout specific session across cluster
• POST /admin/user/logout_all — Logout all users across cluster
• GET /status — Cluster node statuses → Vec<ClusterStatus>

Health check

• GET /api/v1/status — Server health (no auth required), returns HTTP 200

Authentication & authorization

Token-based authentication

1. Call POST /user/login or POST /cluster/user/login with {username, password}.
2. Server returns a token string.
3. Include token in Authorization: Bearer <token> header for subsequent requests.
4. Token expires after token_expiry_seconds (configurable, default 3600, range 60–86400).
5. Expired tokens return 401 Unauthorized.
6. Each login creates a new session; multiple sessions per user are allowed.

Roles and permissions

Users can have roles on databases:

• Admin: Full control (all operations, including backup, restore, rollback, user management)
• Write: Read + modify data (exec_mut)
• Read: Query only (exec, audit)

Admin users have server-wide admin access and are required for user and server operations.

Common error codes

Client libraries

Rust client (agdb_api::AgdbApi)

Hand-written, fully typed. Methods map directly to endpoints. This is the recommended way to interact with the server programmatically.

use agdb_api::{AgdbApi, ReqwestClient, DbKind};
use agdb::QueryBuilder;

let mut client = AgdbApi::new(ReqwestClient::new(), "localhost:3000");

// Authenticate
client.user_login("admin", "password").await?;

// Create database
client.db_add("owner", "my_db", DbKind::Mapped).await?;

// Execute queries
let queries = vec![
    QueryBuilder::insert().nodes().aliases(["root"]).query().into(),
    QueryBuilder::insert().nodes().count(5).query().into(),
];
let (status, results) = client.db_exec_mut("owner", "my_db", &queries).await?;
// results[0].result == 1, results[1].result == 5

// Read back
let (status, results) = client.db_exec("owner", "my_db", &[
    QueryBuilder::select().search().from("root").where_().node().query().into(),
]).await?;

Location: agdb_api/src/client.rs

Package name: agdb_api

Cargo features:

• api (default) — enables derive macros, tokio, and the full client
• derive — agdb derive macros re-exported

Method naming convention: {family}_{resource}_{action}

• admin_db_add, admin_db_exec_mut, admin_user_add
• db_add, db_exec, db_exec_mut, db_backup, db_restore
• cluster_user_login, cluster_status
• user_login, user_logout, user_status

Custom HTTP client: Implement the HttpClient trait to replace ReqwestClient with any HTTP library. The trait defines delete, get, post, put methods.

TypeScript client

Generated from OpenAPI. Includes models and request types.

import { client } from "@agnesoft/agdb_api";

const api = client("http://localhost:3000");
await api.user_login({ username: "admin", password: "password" });
const dbs = await api.db_list();

Location: agdb_api/typescript/src/

Package name: @agnesoft/agdb_api

PHP client

Generated from OpenAPI using openapi-generator.

$api = new \Agnesoft\AgdbApi\Api\AgdbApi(
    new \GuzzleHttp\Client(),
    $config
);
$api->userLogin(['userLogin' => new UserLogin(['username' => 'admin', 'password' => 'password'])]);

Location: agdb_api/php/lib/

Package name: agnesoft/agdb-api

URL: https://packagist.org/packages/agnesoft/agdb_api

Server configuration reference

The server reads a YAML-like config file (default: agdb_server.yaml). First run creates a default config.