API Connectors

API Connectors generate a Starhive SDK, personalized for a specific space's schema, in Java, TypeScript, or Python. The generated SDK includes types/schemas for the space, plus getters, setters, and utility functions, built on top of the Public API.

Generating an SDK

Settings → API & Extensions → API Connectors → pick a space and a language → Generate → download the .zip from the notification.

caution

The SDK is generated at a point in time and won't automatically track schema changes — regenerate it whenever the space's types change. Schema-specific files are stored separately from common ones, to make regenerating easier.

Credentials

Provide a workspace ID and a Personal Access Token, either via a credentials file or environment variables.

Credentials file (~/.starhive/credentials):

starhive_api_token=API_TOKEN_STRING
starhive_workspace_id=WORKSPACE_ID_STRING

Environment variables:

export STARHIVE_API_TOKEN=API_TOKEN_STRING
export STARHIVE_WORKSPACE_ID=WORKSPACE_ID_STRING

Java

Uses a builder pattern per type. For a Fruit type with Name and Colour attributes:

var apple = Fruit.builder()
  .name("Apple")
  .colour("Green")
  .build();

starhiveClient.createObject(apple);

To modify an object, read it, use toBuilder(), and update:

var orange = starhiveClient.getObject(
  UUID.fromString("358e037a-b0c3-4823-9d81-396c96591210"), Fruit.class);
var updatedOrange = orange.toBuilder()
  .colour("Orange")
  .build();
starhiveClient.updateObject(updatedOrange);

Corrected

getObject takes a UUID, not a String (StarhiveClient.java) — the original migrated example passed a string literal directly, which wouldn't compile.

caution

Updating an object clears any values not provided in the update — always read, modify, then update, rather than constructing a partial object from scratch.

Project structure: io.starhive.client holds shared classes; org.example has startup examples; schema-specific code lives in io.starhive.<space-name>, mirroring your type hierarchy.

TypeScript

A bare-bones project using axios for requests and properties-file for configuration:

.
├── package.json
├── src
│   ├── ConfigReader.ts
│   ├── index.ts
│   └── io
│       └── starhive
│           ├── client
│           └── schema
└── tsconfig.json

import Product from './io/starhive/schema/Product'

const getClothes = async () => {
  return await client.search(Product.TYPE_ID, `Category = Clothes`)
}
getClothes()

Python

.
├── src
│   └── starhive
│       └── client
│           └── README.md
│       └── schema
└── main.py

Schema classes live in src.starhive.schema — see that package's README.md and main.py for usage examples.