api websocket javascript rest client integration

Part VI: API and Client Libraries

This section covers how applications talk to Adama. Whether you're building something in the browser, on a phone, or integrating from a backend service, this is where you learn the communication layer.

Overview

Adama gives you three ways to interact with documents:

Method Best For Real-Time Stateless
WebSocket API Browser apps, real-time sync Yes No
JavaScript Client Web/Node.js applications Yes No
REST API Server integrations, webhooks No Yes

Choosing the Right Approach

Use the WebSocket API when:

  • You need real-time state synchronization
  • You're building interactive browser applications
  • Multiple users collaborate on the same document
  • You want automatic reconnection and delta updates

Use the JavaScript Client when:

  • You're building with JavaScript/TypeScript
  • You want a higher-level API over the raw WebSocket
  • You need automatic state management (AdamaTree)
  • You prefer callbacks over raw message handling

Use the REST API when:

  • You're integrating from a server or backend service
  • You're handling webhooks from external services
  • You need one-off document operations
  • Maintaining a WebSocket connection doesn't make sense

The Concepts That Matter

Before diving into specifics, internalize these:

Identity and Authentication

Every request to Adama requires an identity — a JWT token identifying who's making the request. Identities can represent:

  • Anonymous users: Temporary identities for unauthenticated access
  • Developer accounts: Adama platform developer credentials
  • Document-signed users: Users authenticated by document logic
  • Authority-based users: Users from your own authentication system

Spaces and Documents

  • A space is a collection of documents sharing the same Adama schema
  • A key uniquely identifies a document within a space
  • Together, space + key form a document address

The Delta Protocol

Adama uses differential synchronization. Instead of sending the full state every time, the server sends deltas — JSON patches describing what changed. This means:

  • Bandwidth efficiency (only changes go over the wire)
  • Client-side state reconstruction
  • Real-time collaborative editing without re-sending the world

Connections vs Messages

Two interaction patterns:

  1. Streaming Connections: Long-lived WebSocket connections that receive continuous updates
  2. Direct Messages: One-shot message sends without maintaining a connection

Pick based on whether you need to keep listening or just need to fire and forget.

What's In Each Chapter

Chapter Topics
WebSocket API Protocol details, message format, delta protocol, connection lifecycle
JavaScript Client Library usage, connection management, sending messages, handling state
REST API HTTP endpoints, authentication headers, document operations, web handlers

Prerequisites

This section assumes you understand:

  • Basic Adama concepts (spaces, documents, channels)
  • JSON format and HTTP basics
  • JavaScript fundamentals (for the client library chapter)

If those are unfamiliar, start with Part II: Quick Start and Part III: Language.

Quick Reference

Connection URL Format:

wss://{region}.adama-platform.com/~s

REST URL Format:

https://{region}.adama-platform.com/{space}/{key}/{path}

JavaScript Client:

// npm install @anthropic/adama
import { Adama } from '@anthropic/adama';

const connection = new Adama.Connection(Adama.Production);
connection.start();

Start with the WebSocket API.

Previous Reference
Next Websocket Api