Quickstart

This quickstart guide will help you get started with the Litebase API. Follow these steps to set up your environment and make your first API requests.

Introduction

Litebase is the platform for immutable, versioned data. Store key-value data with transactions. Stream events in real time. Query any state, anytime. Build resilient data-driven systems, effortlessly.

Prerequisites

Before you begin, make sure you have:

1. A Litebase account (Apply for access at litebase.io if you don't have one)
2. An API key from the Litebase dashboard

Setting Up Your Environment

To use the Litebase API, you'll need to export your API key as an environment variable. This allows you to securely use your API key in your requests without hardcoding it in your scripts.

For Unix-based systems (Linux, macOS):

export LITEBASE_API_KEY=your_api_key_here

For Windows:

set LITEBASE_API_KEY=your_api_key_here

Making Your First API Requests

Now that you've set up your environment, let's make your first API requests using cURL.

Writing Data with KvWrite

Let's start by adding a new key-value pair to the database:

curl --location 'https://api.litebase.io/sample/kv/write' \
--header 'Content-Type: application/json' \
--header "Authorization: Bearer $LITEBASE_API_KEY" \
--data '[
    {
        "key": "city:1",
        "value": {
            "name": "Braavos"
        }
    }
]'

If successful, you should receive a response similar to:

{
    "$schema": "https://api.litebase.io/schemas/WriteResponse.json",
    "tx": 1,
    "duration": "3.370413ms"
}

Reading Data with KvRead

To retrieve the value you just set, use the following cURL command:

curl --location 'https://api.litebase.io/sample/kv/read' \
--header "Authorization: Bearer $LITEBASE_API_KEY" \
--header 'Content-Type: application/json' \
--data '{
    "keys": ["city:1"]
}'

You should receive a response like this:

{
    "$schema": "https://api.litebase.io/schemas/ReadResponse.json",
    "tx": 1,
    "data": [
        {
            "key": "city:1",
            "tx": 1,
            "value": {
                "name": "Braavos"
            }
        }
    ],
    "duration": "378.06µs"
}

Listing Key-Value Pairs with KvScan

To get a list of all key-value pairs in your namespace, use the KvScan API:

curl --location 'https://api.litebase.io/sample/kv/scan' \
--header "Authorization: Bearer $LITEBASE_API_KEY"

The response will look similar to:

{
    "$schema": "https://api.litebase.io/schemas/ScanResponse.json",
    "tx": 1,
    "data": [
        {
            "key": "city:1",
            "tx": 1,
            "value": {
                "name": "Braavos"
            }
        }
    ],
    "duration": "306.639µs"
}

Working with Transactions

Litebase supports transactions, allowing you to track changes over time.

Updating Existing Data

Let's update the "city:1" key with more information:

curl --location 'https://api.litebase.io/sample/kv/write' \
--header 'Content-Type: application/json' \
--header "Authorization: Bearer $LITEBASE_API_KEY" \
--data '[
    {
        "key": "city:1",
        "value": {
            "name": "Braavos",
            "continent": "Essos"
        }
    }
]'

Notice that the transaction number tx returned in response is increased:

{
    "$schema": "http://api.litebase.io/schemas/WriteResponse.json",
    "tx": 2,
    "duration": "49.505µs"
}

Listing Transactions

To view a list of all transactions in your namespace, use the TxList API:

curl --location 'https://api.litebase.io/sample/tx' \
--header "Authorization: Bearer $LITEBASE_API_KEY"

The response will show all transactions and their associated data changes:

[
    {
        "tx": 2,
        "data": [
            {
                "key": "city:1",
                "value": {
                    "continent": "Essos",
                    "name": "Braavos"
                }
            }
        ]
    },
    {
        "tx": 1,
        "data": [
            {
                "key": "city:1",
                "value": {
                    "name": "Braavos"
                }
            }
        ]
    }
]

Reading Historical Data

By default, KvRead will return latest value of given key. You can read data from a specific transaction by including the tx field in your KvRead request:

curl --location 'https://api.litebase.io/sample/kv/read' \
--header "Authorization: Bearer $LITEBASE_API_KEY" \
--header 'Content-Type: application/json' \
--data '{
    "tx": 1,
    "keys": ["city:1"]
}'

This allows you to compare the value of a key across different transactions.