agnesoft/agdb/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 and exec for query batches, which defaults to JSON via post.

Query encoding: ReqwestClient sends exec/exec_mut batches and receives their results in agdb's binary serialization (BINARY_CONTENT_TYPE, application/vnd.agdb.api.v1) instead of JSON. Servers that predate it answer 415; the client then uses JSON until the server is unreachable or answers 502–504 (e.g. restarted with a newer version).

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.