Litebase

Appearance

Quick Start ​

Welcome to LiteTx, the platform designed to streamline distributed transaction management. This guide will walk you through the basics of interacting with the LiteTx APIs, ensuring a smooth start for developers.

In this guide, you will learn about:

  • What constitutes a transaction
  • How to commit a transaction
  • How to retrieve a transaction by ID
  • How to list recent transactions
  • How to get data versions at a given transaction ID

Transactions ​

In LiteTx, a transaction refers to a sequence of operations executed as a single logical unit of work. Transactions in LiteTx can span across multiple services or databases, potentially across different networks or regions.

LiteTx ensures that distributed transactions maintain ACID properties, despite the complexities of network communication and service dependencies.

typescript
type Transaction = {
  tx: number; 
  read_set: {[key: string]: any};
  write_set: string[];
  data: any;
}
type Transaction = {
  tx: number; 
  read_set: {[key: string]: any};
  write_set: string[];
  data: any;
}
python
from typing import Any, Dict, List, TypedDict

class Transaction(TypedDict):
    tx: int
    read_set: Dict[str, Any]
    write_set: List[str]
    data: Any
from typing import Any, Dict, List, TypedDict

class Transaction(TypedDict):
    tx: int
    read_set: Dict[str, Any]
    write_set: List[str]
    data: Any
  • tx is a number that uniquely identifies the transaction.
  • read_set is an object where the keys are strings representing the data keys and the values are the expected versions of that data.
  • write_set is an array of strings, each representing a key that the transaction aims to update or create.
  • data is typed as any for flexibility, but in a strongly-typed application, it would be replaced with a more precise type matching your data structure.

Examples

typescript
const example: Transaction = {
    tx: 123,
    read_set: {
        "key1": 1,
        "key2": 2
    },
    write_set: ["key3", "key4"],
    data: {
        "key3": "new value for key3",
        "key4": "new value for key4"
    }
}
const example: Transaction = {
    tx: 123,
    read_set: {
        "key1": 1,
        "key2": 2
    },
    write_set: ["key3", "key4"],
    data: {
        "key3": "new value for key3",
        "key4": "new value for key4"
    }
}
python
example: Transaction = {
    "tx": 123,
    "read_set": {"key1": "version1", "key2": "version2"},
    "write_set": ["key3", "key4"],
    "data": {"key3": "new value for key3", "key4": "new value for key4"}
}
example: Transaction = {
    "tx": 123,
    "read_set": {"key1": "version1", "key2": "version2"},
    "write_set": ["key3", "key4"],
    "data": {"key3": "new value for key3", "key4": "new value for key4"}
}

1. Commit a Transaction ​

To commit a transaction, send a POST request to the /tx endpoint:

bash
curl -X POST https://api.litebase.io/tx \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer YOUR_LITEBASE_API_KEY" \
  -d '{
    "read_set": {"key1": 1, "key2": 2},
    "write_set": ["key3", "key4"],
    "data": {
      "key3": "new value for key3",
      "key4": "new value for key4"
    }
  }'
curl -X POST https://api.litebase.io/tx \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer YOUR_LITEBASE_API_KEY" \
  -d '{
    "read_set": {"key1": 1, "key2": 2},
    "write_set": ["key3", "key4"],
    "data": {
      "key3": "new value for key3",
      "key4": "new value for key4"
    }
  }'
typescript
const response = await fetch('https://api.litebase.io/tx', {
  method: 'POST',
  headers: {
    'Content-Type': 'application/json',
    'Authorization': 'Bearer YOUR_LITEBASE_API_KEY'
  },
  body: JSON.stringify({
    read_set: { "key1": 1, "key2": 2 },
    write_set: ["key3", "key4"],
    data: {
      key3: "new value for key3",
      key4: "new value for key4"
    }
  })
});
const data = await response.json();
const response = await fetch('https://api.litebase.io/tx', {
  method: 'POST',
  headers: {
    'Content-Type': 'application/json',
    'Authorization': 'Bearer YOUR_LITEBASE_API_KEY'
  },
  body: JSON.stringify({
    read_set: { "key1": 1, "key2": 2 },
    write_set: ["key3", "key4"],
    data: {
      key3: "new value for key3",
      key4: "new value for key4"
    }
  })
});
const data = await response.json();

Expected Response:

json
{
  "tx": 123,
  "duration": "120ns"
}
{
  "tx": 123,
  "duration": "120ns"
}

2. Retrieve a Transaction by ID ​

To fetch a specific transaction by ID, use the GET /tx/:id endpoint, replacing :id with the actual transaction ID.

bash
curl -X GET https://api.litebase.io/tx/123 \
  -H "Accept: application/json" \
  -H "Authorization: Bearer YOUR_LITEBASE_API_KEY"
curl -X GET https://api.litebase.io/tx/123 \
  -H "Accept: application/json" \
  -H "Authorization: Bearer YOUR_LITEBASE_API_KEY"
typescript
const response = await fetch(`https://api.litebase.io/tx/${txId}`, {
  method: 'GET',
  headers: {
    'Accept': 'application/json',
    'Authorization': 'Bearer YOUR_LITEBASE_API_KEY'
  }
});
const transactionDetails = await response.json();
const response = await fetch(`https://api.litebase.io/tx/${txId}`, {
  method: 'GET',
  headers: {
    'Accept': 'application/json',
    'Authorization': 'Bearer YOUR_LITEBASE_API_KEY'
  }
});
const transactionDetails = await response.json();

Expected Response:

json
{
  "tx": 123,
  "read_set": {"key1": 1, "key2": 2},
  "write_set": ["key3", "key4"],
  "data": {
    "key3": "value for key3",
    "key4": "value for key4"
  }
}
{
  "tx": 123,
  "read_set": {"key1": 1, "key2": 2},
  "write_set": ["key3", "key4"],
  "data": {
    "key3": "value for key3",
    "key4": "value for key4"
  }
}

3. List Recent Transactions ​

To list recent transactions, make a GET request to the /tx endpoint. You can include optional query parameters like max_tx for the maximum transaction ID and limit for the number of transactions to retrieve.

bash
curl -X GET "https://api.litebase.io/tx?max_tx=150&limit=10" \
  -H "Accept: application/json" \
  -H "Authorization: Bearer YOUR_LITEBASE_API_KEY"
curl -X GET "https://api.litebase.io/tx?max_tx=150&limit=10" \
  -H "Accept: application/json" \
  -H "Authorization: Bearer YOUR_LITEBASE_API_KEY"
typescript
const response = await fetch(`https://api.litebase

.io/tx?max_tx=${maxTx}&limit=${limit}`, {
  method: 'GET',
  headers: {
    'Accept': 'application/json',
    'Authorization': `Bearer ${YOUR_LITEBASE_API_KEY}`
  }
});
const recentTransactions = await response.json();
const response = await fetch(`https://api.litebase

.io/tx?max_tx=${maxTx}&limit=${limit}`, {
  method: 'GET',
  headers: {
    'Accept': 'application/json',
    'Authorization': `Bearer ${YOUR_LITEBASE_API_KEY}`
  }
});
const recentTransactions = await response.json();

Expected Response:

json
[
  {
    "tx": 150,
    "read_set": {"key1": 1, "key2": 2},
    "write_set": ["key3", "key4"],
    "data": {
      "key3": "value for key3",
      "key4": "value for key4"
    }
  },
  // ... other transactions
]
[
  {
    "tx": 150,
    "read_set": {"key1": 1, "key2": 2},
    "write_set": ["key3", "key4"],
    "data": {
      "key3": "value for key3",
      "key4": "value for key4"
    }
  },
  // ... other transactions
]

4. Get Data Versions ​

To retrieve the versions of data at a specific transaction ID, use the GET /versions endpoint.

bash
curl -X GET "https://api.litebase.io/versions?tx=123&keys=key1,key2" \
  -H "Accept: application/json" \
  -H "Authorization: Bearer YOUR_LITEBASE_API_KEY"
curl -X GET "https://api.litebase.io/versions?tx=123&keys=key1,key2" \
  -H "Accept: application/json" \
  -H "Authorization: Bearer YOUR_LITEBASE_API_KEY"

Expected Response:

json
{
  "tx": 123,
  "data": {
    "key1": 1,
    "key2": 2
  },
  "duration": "5ms"
}
{
  "tx": 123,
  "data": {
    "key1": 1,
    "key2": 2
  },
  "duration": "5ms"
}