API Documentation

Complete usage guide for the OpenDBS REST API. Manage databases, perform advanced search, and handle backups entirely via HTTP requests. Default server runs on port 4402.

1. Authentication

All requests require a Bearer token. On fresh install, use the default admin credentials.

Default Credentials:
Username: admin
Password: admin123

bash

# Login to get your Bearer Token
curl -X POST http://localhost:4402/api/auth/login \
  -H "Content-Type: application/json" \
  -d '{
    "username": "admin",
    "password": "admin123"
  }'

# Response:
# { "token": "eyJhb..." }

2. User Management

Create New User

Admin only allows creating new users with specific permissions.

bash

curl -X POST http://localhost:4402/api/auth/register \
  -H "Authorization: Bearer $ADMIN_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "username": "developer",
    "password": "securePass123",
    "role": "user",
    "permissions": {
       "ecommerce": ["read", "write"]
    }
  }'

Reset Password (Admin Force)

Admins can update any user's password or details.

bash

# Update password for user ID "123"
curl -X PATCH http://localhost:4402/api/auth/users/123 \
  -H "Authorization: Bearer $ADMIN_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "password": "newPassword456"
  }'

Update Own Password

Users can change their own password safely.

bash

curl -X PUT http://localhost:4402/api/auth/me/password \
  -H "Authorization: Bearer $TOKEN" \
  -d '{ "password": "myNewPassword" }'

3. Database Management

Create a new isolated database environment.

bash

# Create a new database named 'ecommerce'
curl -X POST http://localhost:4402/api/databases \
  -H "Authorization: Bearer $TOKEN" \
  -d '{"name": "ecommerce"}'

4. Rack Management (SQL & NoSQL)

Racks are collections or tables. You can define them as sql (rigid schema) or nosql (flexible schema).

Create SQL Rack

Enforces schema validation. Accepts only SQL operations.

bash

curl -X POST http://localhost:4402/api/databases/ecommerce/racks \
  -H "Authorization: Bearer $TOKEN" \
  -d '{
    "name": "products",
    "type": "sql",
    "schema": {
      "name": {"type": "string", "required": true},
      "price": {"type": "number", "required": true},
      "inStock": {"type": "boolean"}
    }
  }'

Create NoSQL Rack

Flexible JSON documents. Accepts both NoSQL and SQL operations.

bash

curl -X POST http://localhost:4402/api/databases/ecommerce/racks \
  -H "Authorization: Bearer $TOKEN" \
  -d '{"name": "users", "type": "nosql"}'

5. CRUD Operations

Insert (NoSQL)

bash

curl -X POST .../racks/users/documents \
  -H "Authorization: Bearer $TOKEN" \
  -d '{
    "name": "Alice",
    "email": "alice@example.com",
    "role": "admin"
  }'

Insert (SQL)

bash

curl -X POST .../sql/ecommerce/execute \
  -H "Authorization: Bearer $TOKEN" \
  -d '{
    "query": "INSERT INTO products (name, price) VALUES ('\'Laptop'\', 999)"
  }'

Update

bash

# Update via ID
curl -X PUT .../racks/users/documents/1 \
  -H "Authorization: Bearer $TOKEN" \
  -d '{"role": "manager"}'

Delete

bash

# Delete via ID
curl -X DELETE .../racks/users/documents/1 \
  -H "Authorization: Bearer $TOKEN"

6. Foreign Keys & Relations

Link documents across racks using the format rack_name:id.

bash

# 1. Create a profile (ID generated: "1")
curl -X POST .../racks/profiles/documents -d '{"bio": "Dev"}'

# 2. Link user to profile
curl -X POST .../racks/users/documents \
  -d '{
    "name": "Bob",
    "profile_id": "profiles:1"  // points to profiles rack, id 1
  }'

# 3. Fetch with Population
curl ".../racks/users/documents?populate=true"

7. Advanced Search

Perform complex queries including Fuzzy matching, Vector similarity, and Range filters.

Vector Search (Semantic)

bash

curl -X POST .../racks/products/search/vector \
  -d '{
    "field": "embedding",
    "vector": [0.1, 0.4, 0.9, -0.1],
    "k": 5
  }'

Fuzzy Search (Typo Tolerance)

bash

# Finds "John" even if query is "Jon"
curl -X POST .../racks/users/search/fuzzy \
  -d '{ "field": "name", "query": "Jon" }'

Range & Filter Search

bash

# Find users age 25-35 in NY or London
curl -X POST .../racks/users/search \
  -d '{
    "query": {
      "age": { "$gte": 25, "$lte": 35 },
      "city": { "$in": ["NY", "London"] }
    }
  }'

8. Backup & Restore

Configure automatic backups to S3, FTP, or Local Disk via .env.

Quick JSON Export

Download your data instantly without server configuration.

curl "http://localhost:4402/api/backup/quick?database=myapp" --output myapp.zip

Configuration (.env)

bash

BACKUP_ENABLED=true
BACKUP_SCHEDULE="0 2 * * *"  # Daily at 2am
BACKUP_TYPE=s3               # or local, ftp

# S3 Config
BACKUP_S3_BUCKET=my-backups
BACKUP_S3_REGION=us-east-1
BACKUP_S3_ACCESS_KEY=xxx
BACKUP_S3_SECRET_KEY=xxx

Ready to build?

Start your local instance and begin developing in minutes.

Back to Home