Content Management API

Manage your game content programmatically.

Overview

Data builds are immutable binary files created from your Google Spreadsheets using your Basilisk Definition. They are published to environments and can be fetched by your application.

The Web Console generates Protocol Buffer definitions and classes from your BDL files, which you use to deserialize the data builds in your application.

Fetching Data Builds

Once a data build is published to an environment, you can fetch it from the environment's endpoint. The endpoint URL is provided in the Web Console.

// JavaScript/TypeScript example
const response = await fetch('https://your-environment.basilisk.io/data-builds/latest');
const dataBuild = await response.arrayBuffer();

// Deserialize using Protocol Buffers
import { BinaryReader } from '@bufbuild/protobuf/wire';
import { YourDataBundle } from './generated/your-definition';

const reader = new BinaryReader(dataBuild);
const bundle = YourDataBundle.decode(reader);

// Access your data
console.log(bundle.characters); // Access entities by bundle name

Python Example

import requests
import your_definition_pb2

# Fetch the data build
response = requests.get('https://your-environment.basilisk.io/data-builds/latest')
data_build = response.content

# Deserialize
bundle = your_definition_pb2.YourDataBundle()
bundle.ParseFromString(data_build)

# Access your data
print(bundle.characters)

C# Example

using Google.Protobuf;
using YourNamespace;

// Fetch the data build
var client = new HttpClient();
var response = await client.GetAsync("https://your-environment.basilisk.io/data-builds/latest");
var dataBuild = await response.Content.ReadAsByteArrayAsync();

// Deserialize
var bundle = YourDataBundle.Parser.ParseFrom(dataBuild);

// Access your data
Console.WriteLine(bundle.Characters);

Accessing Data

Once deserialized, you can access your data using the structure defined in your BDL:

By bundle: Access entities grouped in data bundles
By index: Use indexes for efficient lookups
By primary key: Look up entities by their primary key
By reference: Follow references between entities

// Example: Accessing entities
const character = bundle.characters.get('character-id-123');
console.log(character.name);
console.log(character.level);
console.log(character.health);

// Using indexes
const characterIndex = bundle.characterIndex;
const characterById = characterIndex.get('character-id-123');

// Following references
const weaponId = character.weaponId;
const weapon = bundle.weapons.get(weaponId);

Caching Strategies

Since data builds are immutable, they can be cached effectively:

Build ID caching: Cache builds by their build ID to ensure you're using the correct version
ETag support: Use ETags to check if a new build is available without downloading
Update polling: Poll for new builds based on your cadence (e.g., weekly, monthly)
Hot reload: Implement hot reloading to update data without restarting your application

// Example: Caching with ETag
const cachedBuild = localStorage.getItem('data-build-id');
const response = await fetch('https://your-environment.basilisk.io/data-builds/latest', {
  headers: {
    'If-None-Match': cachedBuild?.etag,
  },
});

if (response.status === 304) {
  // No changes, use cached build
  return cachedBuild.data;
}

// New build available
const newBuild = await response.arrayBuffer();
const newEtag = response.headers.get('ETag');
localStorage.setItem('data-build-id', { etag: newEtag, data: newBuild });
return newBuild;

Error Handling

When fetching and deserializing data builds:

Handle network errors gracefully
Validate that the data build matches your expected Protocol Buffer definition
Fall back to cached builds if fetching fails
Log errors for debugging and monitoring
Implement retry logic for transient failures

Getting Protocol Buffer Definitions

The Web Console provides download links for:

Protocol Buffer definition files (.proto)
Generated classes for your programming language
Integration examples and documentation

Download these files from the Basilisk Definition details page in the Web Console. See the Creating Content guide for more information about definitions. Creating Content.