The key uniquely identifies the key-value pair within the World State database. The most appropriate method for constructing keys varies by use case. For example, if you are only interested in the append-only nature of the XLDB, and not in the state database, or rich query, it doesn’t matter what you use as a key, and you may find it convenient to use the same key for all transactions. You can use the History endpoint to fetch all transactions and their associated payloads.

If you wish to search based on the content of each transaction (the payload), you will then need a unique key (such as uuid) for each transaction because such a search can run only against the State Database (see Query endpoint for more details).

The XLDB State Database may be used to store different object types (such as cars and people), typically using different JSON document schemas. If this is your use case, it makes sense to combine the object type and the unique object identifier into a single key. Another best practice with multiple object types is to denote the object type within the JSON representation of the value. It will facilitate query filtering by object types.

It is recommended that values are formatted as JSON objects to effectively utilize the rich query capabilities of the query endpoint.

The XLDB enriches values with metadata fields such as the identity of the token holder that created or modified the key, along with the created and the last-modified date. These metadata fields may be used to filter a query using the Query endpoint.

More details on the XLDB APIs can be read and tried here.

More details about World State, Transactions, and other app-related features can be read here.

Do you prefer video tutorials? Check out the video tutorial for XLDB here.

Using Xooa console

We can invoke functions directly from the UI. You won’t even need the API token.

1. Go to the World State tab, and then select Add.

2. Select Use Sample. It will populate the key and value fields for you.

3. Click Save.

Using API Explorer

We can invoke functions from the API documentation, but you will need the API token.

Let’s create an API token first.

1. Go to the XLDB > Identities tab, and then click Add New.

2. Enter an identity name and under API Access Permission, select Read+Write.

3. Click Create. You’ll get a message that the identity has been enrolled and the API token generated.

4. Before you dismiss the message, click Copy. The token is now in the clipboard.

5. Store the token somewhere safe. You will need it to authorize every API request.

Let’s invoke functions from the API documentation.

1. Go to the API tab, and then click Explore APIs. The API Explorer, including the API documentation, will open.

2. At the top left, there is an input field for the API token. Paste the token that you copied earlier here.

3. From the navigation, go to XLDB > Create.

4. In the key-value field, enter the data you want to store in the ledger in the format:

   [ "<key>", "<value>" ]

5. Click TRY.

    

   Congrats!

   If your HTTP response code was 200, you have saved data in a blockchain ledger by using Xooa. Check instructions in the message or the API documentation for other return codes.

1. To view transactions, go to Transactions tab inside the app.
2. Click the tx ID to get additional details about the transaction
3. To view World State, go to World State.
4. Expand the row from listed states to get the detailed structure of values.