Quickstart guide using BigState Api

Requirements#

Node.js version 18.0 or above (which can be checked by running node -v). You can use nvm for managing multiple Node versions on a single machine installed. When installing Node.js, you are recommended to check all checkboxes related to dependencies.

$ https://nodejs.org/en/download/package-manager

Installation#

npm install bigstate.client.javascript

Basic usage#

The imported BigStateHttpClient class allows you to create a client with a base URL.:

import { BigStateHttpClient } from 'bigstate.client.javascript';

export const client = new BigStateHttpClient({
  baseUrl: 'https://',
  apiKey: 'YOUR_API_KEY'
  // or: token: 'YOUR_TOKEN'
});

The client encapsulates the network interaction and serves as a convenient entry point for making requests to the backend. The setup consists of transferring the configuration, after which the client is ready for use throughout the application.

Configuration#

Below is a list of the allowed properties.

• baseUrl - required - string - this is the root URL to which the client will automatically add the paths of all its HTTP requests. This is the "entry point" to API.
• apiKey - optional - string - the API key used to authenticate requests. It is transmitted to the client if access to service is based on static keys. If an apiKey is specified, the token field is usually not required. How get an ApiKey?
• token - optional - string - the access window that is used to authorize requests. If a token is specified, the apiKey field can be omitted.

First API Call#

Once your client is initialized, you can perform your first request. This example demonstrates a minimal GET call to the BigState API.

const response = await client.authInfoGet();
console.log(response.data);

This snippet shows the basic structure of an API call: sending a request and reading the returned data.

Minimal Working Example#

A complete, ready-to-run example including import, client setup, authentication, and the first request.

import { BigStateHttpClient } from 'bigstate.client.javascript';

async function main() {
  const client = new BigStateHttpClient({
    baseUrl: 'https://api.bigstate.dev',
    apiKey: 'YOUR_API_KEY'
    // or: token: 'YOUR_TOKEN'
  });

  const sid = 'user:current:location';

  const subject = {
    name: 'Current User Location',
    desc: 'Dynamic geolocation point representing the user’s current position. Can be updated anytime as the user moves.',
    example: { latitude: 40.712776, longitude: -74.005974 },
    type: 2
  }

  await client.subjectCreate(subject, sid);

  const response = await client.subjectGet(sid);
  console.log(response.data);
}

main();

You can paste this directly into your project — it works out of the box once you provide a valid token or API key.

Error Handling#

BigStateClient does not throw errors automatically — instead, every request returns an object that includes both data and error. This allows you to handle errors in any way you prefer.

const sid = 'user:current:location';
const { data, error } = await client.subjectGet(sid);

if (error) {
  console.error('BigState API error:', error.message);
  console.log('Code:', error.code);
} else {
  console.log('Subject:', data);
}

Common error code scenarios:

• 401 Unauthorized — invalid apiKey or token

• 404 Not Found — incorrect endpoint

• 400 Bad Request — invalid input parameters

• 500+ Server Error — issue on the BigState server side