MatsushibaDB

API Reference

Part of Matsushiba Systems

API Reference

Complete API documentation for MatsushibaDB with examples and code snippets.

Authentication

JWT tokens and user management

Database

Query execution and transactions

Admin

System administration and monitoring

WebSocket

Real-time communication

TCP

Binary protocol interface

Error Codes

Error handling and status codes

Authentication API

POST /auth/login

Authenticate user and receive JWT token

Request

POST /auth/login
Content-Type: application/json

{
  "username": "admin",
  "password": "password"
}

Response

HTTP/1.1 200 OK
Content-Type: application/json

{
  "success": true,
  "token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...",
  "user": {
    "id": 1,
    "username": "admin",
    "role": "admin",
    "permissions": ["read", "write", "admin"]
  },
  "expires_in": 3600
}

Error Response

HTTP/1.1 401 Unauthorized
Content-Type: application/json

{
  "success": false,
  "error": "Invalid credentials",
  "code": "AUTH_INVALID_CREDENTIALS"
}

POST /auth/logout

Invalidate JWT token

Request

POST /auth/logout
Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...

Response

HTTP/1.1 200 OK
Content-Type: application/json

{
  "success": true,
  "message": "Logged out successfully"
}

GET /auth/me

Get current user information

Request

GET /auth/me
Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...

Response

HTTP/1.1 200 OK
Content-Type: application/json

{
  "success": true,
  "user": {
    "id": 1,
    "username": "admin",
    "role": "admin",
    "permissions": ["read", "write", "admin"],
    "created_at": "2025-01-01T00:00:00Z",
    "last_login": "2025-01-24T10:30:00Z"
  }
}

Database API

POST /db/query

Execute SQL query

Request

POST /db/query
Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...
Content-Type: application/json

{
  "query": "SELECT * FROM users WHERE id = ?",
  "params": [123]
}

Response

HTTP/1.1 200 OK
Content-Type: application/json

{
  "success": true,
  "data": [
    {
      "id": 123,
      "name": "John Doe",
      "email": "john@example.com",
      "created_at": "2025-01-01T00:00:00Z"
    }
  ],
  "meta": {
    "rows_affected": 1,
    "execution_time": 5,
    "query_id": "q_123456789"
  }
}

POST /db/transaction

Execute multiple queries in a transaction

Request

POST /db/transaction
Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...
Content-Type: application/json

{
  "queries": [
    {
      "query": "INSERT INTO users (name, email) VALUES (?, ?)",
      "params": ["John Doe", "john@example.com"]
    },
    {
      "query": "INSERT INTO profiles (user_id, bio) VALUES (?, ?)",
      "params": ["$last_insert_id", "Software Developer"]
    }
  ]
}

Response

HTTP/1.1 200 OK
Content-Type: application/json

{
  "success": true,
  "results": [
    {
      "success": true,
      "data": null,
      "meta": {
        "rows_affected": 1,
        "last_insert_id": 124
      }
    },
    {
      "success": true,
      "data": null,
      "meta": {
        "rows_affected": 1,
        "last_insert_id": 125
      }
    }
  ],
  "transaction_id": "tx_123456789"
}

GET /db/schema

Get database schema information

Request

GET /db/schema
Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...

Response

HTTP/1.1 200 OK
Content-Type: application/json

{
  "success": true,
  "schema": {
    "tables": [
      {
        "name": "users",
        "columns": [
          {
            "name": "id",
            "type": "INTEGER",
            "primary_key": true,
            "not_null": true
          },
          {
            "name": "name",
            "type": "TEXT",
            "primary_key": false,
            "not_null": true
          },
          {
            "name": "email",
            "type": "TEXT",
            "primary_key": false,
            "not_null": false,
            "unique": true
          }
        ],
        "indexes": [
          {
            "name": "idx_users_email",
            "columns": ["email"],
            "unique": true
          }
        ]
      }
    ]
  }
}

Admin API

GET /admin/stats

Get system statistics

Request

GET /admin/stats
Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...

Response

HTTP/1.1 200 OK
Content-Type: application/json

{
  "success": true,
  "stats": {
    "server": {
      "uptime": 86400,
      "version": "1.0.8",
      "start_time": "2025-01-23T10:30:00Z"
    },
    "database": {
      "size": "50MB",
      "tables": 5,
      "indexes": 8,
      "connections": 5
    },
    "performance": {
      "queries_per_second": 150,
      "average_response_time": 5,
      "total_queries": 12960000
    },
    "memory": {
      "used": "25MB",
      "free": "75MB",
      "cache_hits": 0.95
    }
  }
}

GET /admin/users

List all users (admin only)

Request

GET /admin/users
Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...

Response

HTTP/1.1 200 OK
Content-Type: application/json

{
  "success": true,
  "users": [
    {
      "id": 1,
      "username": "admin",
      "role": "admin",
      "created_at": "2025-01-01T00:00:00Z",
      "last_login": "2025-01-24T10:30:00Z",
      "active": true
    },
    {
      "id": 2,
      "username": "user1",
      "role": "user",
      "created_at": "2025-01-02T00:00:00Z",
      "last_login": "2025-01-24T09:15:00Z",
      "active": true
    }
  ]
}

POST /admin/users

Create new user (admin only)

Request

POST /admin/users
Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...
Content-Type: application/json

{
  "username": "newuser",
  "password": "securepassword",
  "role": "user"
}

Response

HTTP/1.1 201 Created
Content-Type: application/json

{
  "success": true,
  "user": {
    "id": 3,
    "username": "newuser",
    "role": "user",
    "created_at": "2025-01-24T10:30:00Z",
    "active": true
  }
}

GET /admin/audit

Get audit logs (admin only)

Request

GET /admin/audit?limit=100&offset=0&user=admin&action=SELECT
Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...

Response

HTTP/1.1 200 OK
Content-Type: application/json

{
  "success": true,
  "audit_logs": [
    {
      "id": 1,
      "timestamp": "2025-01-24T10:30:00Z",
      "user": "admin",
      "action": "SELECT",
      "table": "users",
      "query": "SELECT * FROM users WHERE id = ?",
      "parameters": [123],
      "ip": "192.168.1.100",
      "success": true,
      "execution_time": 5
    }
  ],
  "pagination": {
    "total": 1000,
    "limit": 100,
    "offset": 0,
    "has_more": true
  }
}

WebSocket API

WebSocket Connection

Real-time communication via WebSocket

Connection

const ws = new WebSocket('ws://localhost:8001', {
  headers: {
    'Authorization': 'Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...'
  }
});

Message Format

// Request
{
  "id": "req_123",
  "type": "query",
  "data": {
    "query": "SELECT * FROM users",
    "params": []
  }
}

// Response
{
  "id": "req_123",
  "type": "query_result",
  "success": true,
  "data": [
    {
      "id": 1,
      "name": "John Doe",
      "email": "john@example.com"
    }
  ],
  "meta": {
    "execution_time": 5,
    "rows_affected": 1
  }
}

Message Types

  • query - Execute SQL query
  • subscribe - Subscribe to table changes
  • unsubscribe - Unsubscribe from table changes
  • ping - Keep-alive ping
  • pong - Keep-alive pong

Real-time Updates

// Subscribe to table changes
ws.send(JSON.stringify({
  "id": "sub_123",
  "type": "subscribe",
  "data": {
    "table": "users",
    "events": ["insert", "update", "delete"]
  }
}));

// Receive real-time updates
ws.onmessage = (event) => {
  const message = JSON.parse(event.data);
  if (message.type === 'table_change') {
    console.log('Table changed:', message.data);
  }
};

TCP API

TCP Protocol

Binary protocol for high-performance communication

Connection

const net = require('net');

const client = new net.Socket();
client.connect(8002, 'localhost', () => {
  console.log('Connected to MatsushibaDB TCP server');
});

Message Format

// Binary message format
// Header (8 bytes)
// [4 bytes: message length][4 bytes: message type]

// Message types
const MESSAGE_TYPES = {
  QUERY: 1,
  QUERY_RESULT: 2,
  ERROR: 3,
  AUTH: 4,
  AUTH_RESULT: 5,
  PING: 6,
  PONG: 7
};

// Query message
const queryMessage = Buffer.concat([
  Buffer.from([0, 0, 0, 20]), // Length: 20 bytes
  Buffer.from([0, 0, 0, 1]),   // Type: QUERY
  Buffer.from('SELECT * FROM users', 'utf8')
]);

Authentication

// Send authentication
const authMessage = Buffer.concat([
  Buffer.from([0, 0, 0, 20]), // Length: 20 bytes
  Buffer.from([0, 0, 0, 4]),   // Type: AUTH
  Buffer.from('admin:password', 'utf8')
]);

client.write(authMessage);

Error Codes

Authentication Errors

AUTH_INVALID_CREDENTIALS

Invalid username or password

AUTH_TOKEN_EXPIRED

JWT token has expired

AUTH_TOKEN_INVALID

Invalid or malformed JWT token

AUTH_INSUFFICIENT_PERMISSIONS

User lacks required permissions

Database Errors

DB_QUERY_SYNTAX_ERROR

Invalid SQL syntax

DB_CONSTRAINT_VIOLATION

Database constraint violation

DB_TABLE_NOT_FOUND

Table does not exist

DB_COLUMN_NOT_FOUND

Column does not exist

System Errors

SYS_CONNECTION_LIMIT

Maximum connections exceeded

SYS_RATE_LIMIT_EXCEEDED

Rate limit exceeded

SYS_DATABASE_LOCKED

Database is locked

SYS_INTERNAL_ERROR

Internal server error

Error Response Format

HTTP/1.1 400 Bad Request
Content-Type: application/json

{
  "success": false,
  "error": "Invalid SQL syntax",
  "code": "DB_QUERY_SYNTAX_ERROR",
  "details": {
    "query": "SELCT * FROM users",
    "position": 5,
    "suggestion": "Did you mean 'SELECT'?"
  },
  "timestamp": "2025-01-24T10:30:00Z",
  "request_id": "req_123456789"
}