Product guidance

Ably provides multiple interfaces and SDKs to suit different use cases, platforms, and requirements. This guide helps you choose the right approach for your application.

Overview

When building with Ably, you need to make several decisions:

1. Which product: Pub/Sub, Chat, Spaces, LiveObjects, LiveSync, or AI Transport
2. Which features: Rules for per-namespace configuration, push notifications for offline and native push delivery
3. Which interface: REST, Realtime, or protocol adapters

The right choice depends on your application's requirements for latency, connection persistence, and the complexity of the features you're building. These choices also have pricing implications, as different interfaces and connection patterns affect how your usage is metered.

Purpose-built SDKs vs Pub/Sub

Ably provides purpose-built SDKs that abstract away the complexity of building common realtime features. These SDKs are built on top of Pub/Sub and benefit from all the same platform guarantees.

Pub/Sub

Pub/Sub is Ably's core product. It provides flexible, low-level APIs for publishing and subscribing to messages on channels, giving you full control over your message architecture.

Pub/Sub is a good fit when:

• You need maximum flexibility in message structure and channel design.
• You're building custom realtime features not covered by purpose-built SDKs.
• You need to integrate with existing backend systems.

Pub/Sub gives you direct access to Ably's underlying messaging primitives, including channels, presence, and history, enabling you to design your own message architecture.

Chat SDK

Ably Chat provides purpose-built APIs for building chat functionality, including rooms, messages, typing indicators, reactions, and presence.

Chat is a good fit when you're building:

• 1:1 customer support chat.
• Group conversations.
• Livestream chat with thousands of users.
• Or any application requiring chat functionality.

The Chat SDK provides:

Spaces SDK

Ably Spaces provides high-level APIs for building collaborative environments where users work together in realtime.

Spaces is a good fit when you're building:

• Interactive whiteboards with live cursors.
• Collaborative document editing.
• Avatar stacks showing online users.
• Applications with component locking to prevent edit conflicts.

The Spaces SDK is optimized for participant state, which is largely ephemeral and doesn't need to be stored. This is distinct from application state, which must be validated and stored in your database.

The Spaces SDK provides:

LiveObjects

Ably LiveObjects provides the ability to associate durable state with a channel. Participants can use and modify that state concurrently, with conflicts resolved automatically, and clients can use that state to hydrate.

LiveObjects is a good fit when:

• The state is more naturally represented as a structured collection of objects and/or primitive values.
• Your application needs a way to structure and manage the state explicitly.

LiveObjects provides:

Pub/Sub channels, without LiveObjects, can also be used as a durable store of channel state, and for client hydration, but in this case the state is simply the content of messages sent on the channel, retrieved using features such as history and rewind.

LiveSync

Ably LiveSync synchronizes your database state to frontend clients in realtime, whilst having only a single write path.

LiveSync is a good fit when:

• Your database is the source of truth for application state.
• You need to reflect database changes to clients in realtime.
• You want to enable optimistic updates in the UI.
• You're using PostgreSQL or MongoDB.

AI Transport

Ably AI Transport provides purpose-built APIs for streaming AI-generated content to users in realtime, handling token streaming, session management, and multi-user fan-out.

AI Transport is a good fit when:

• You're building applications that stream LLM responses to users in realtime.
• You need to manage AI chat sessions with identity and resumability.
• You want to fan out AI-generated content to multiple subscribers.

Why use purpose-built SDKs

Purpose-built SDKs provide an API optimized for specific use cases:

• Additional use-case-specific functionality beyond raw Pub/Sub.
• A more targeted and opinionated API that's a natural fit for the application.
• Non-default channel behavior applied as appropriate for the use case (such as enabling persistence).
• Developer guides tailored to the use case.
• Simplified design decisions, reducing friction and helping you succeed as easily as possible.

REST vs Realtime interface

Ably SDKs contain both a REST and a Realtime interface. Each serves different use cases.

REST interface

The REST interface communicates with Ably using HTTP and is effectively stateless. It does not maintain a persistent connection to Ably.

Use the REST interface when you need to:

• Publish messages from a server without receiving updates.
• Issue tokens on behalf of other clients.
• Retrieve message history, presence history, or application statistics.
• Perform occasional, request-response style operations.
• Minimize resource usage in environments where persistent connections are impractical.

The REST interface is more commonly used server-side. It is more efficient if you don't need to establish a persistent connection to Ably, such as when you have a server publishing messages to channels that doesn't need to receive any updates from them.

Serverless and cloud functions

Use the REST interface when publishing from serverless environments such as AWS Lambda, Google Cloud Functions, Azure Functions, or Cloudflare Workers. These environments are designed for short-lived, stateless execution and do not support persistent WebSocket connections.

The REST interface is also the appropriate choice when handling inbound webhooks from Ably. Your webhook handler receives event data via HTTP and can publish responses or trigger actions using the REST interface.

Realtime interface

The Realtime interface uses an Ably-defined protocol, primarily over WebSockets, to establish and maintain a persistent connection to Ably. The Realtime interface extends the functionality of the REST interface.

Use the Realtime interface when you need to:

• Subscribe to messages in realtime.
• Maintain a persistent connection to Ably.
• Attach to one or more channels and publish and subscribe to messages.
• Register presence on a channel, or listen for others present in realtime.
• Publish at very high message rates, or with the lowest possible latencies.
• Benefit from automatic reconnection and connection state recovery.

The Realtime interface is most commonly used client-side. Subscribing to messages is only available through the Realtime interface because it requires establishing a persistent connection to Ably in order to receive messages in realtime.

Comparison

REST HTTP API vs SDK REST interface

Ably provides a REST HTTP API that you can use directly without an SDK.

Use the REST interface of an Ably SDK when:

• You want automatic re-routing around network problems via alternative datacenters and other resilience features.
• You prefer a language-idiomatic API.

Use the REST HTTP API directly when:

• No Ably SDK is available for your platform.
• You want to avoid having any third-party SDK in your app or SDK.

Ably recommends using SDK REST interfaces where possible. SDKs provide additional features that improve performance and resilience that the REST HTTP API cannot deliver on its own, such as automatic re-routing around network problems by using alternative datacenters.

Protocol adapters

Ably SDKs are the recommended method for connecting to Ably. They provide comprehensive feature support including automatic connection management, authentication token renewal, and APIs for the full range of Ably functionality.

Protocol adapters offer an alternative for specific scenarios where SDKs are impractical.

When to use SDKs

Use an Ably SDK when:

• An SDK is available for your platform.
• You need the full set of Ably features.
• You want automatic connection recovery and token renewal.
• You're building a production application.

When to use protocol adapters

Consider protocol adapters when:

• There is no Ably SDK available for your platform (such as embedded or IoT devices).
• You are migrating from another messaging service (such as Pusher or PubNub) and want to minimise the cost and risk of transition.
• You want to avoid including any third-party SDK in your own application or SDK (such as for footprint reasons), and are able to use a subset of features that's supportable without an Ably SDK.

Available protocol adapters:

Protocol adapters do not support the full set of Ably features. For example, the MQTT protocol adapter does not support presence, and the SSE protocol does not support message publishing.

Combining SDKs with Pub/Sub

Purpose-built SDKs like Chat and Spaces are built on top of the Ably Pub/Sub SDK. When you initialize a purpose-built SDK, it creates or accepts an underlying Ably Realtime client. This means you can use that same client to interact with Pub/Sub channels directly, sharing a single connection to Ably rather than opening multiple connections. Use your own channels for custom Pub/Sub features, but do not interact directly with channels managed by the purpose-built SDK.

Accessing the underlying Realtime client

The Chat and Spaces SDKs expose the underlying Ably Realtime client that powers them. This client is the same one you would use directly with Pub/Sub, giving you access to all of its functionality.

There are several benefits to this architecture:

• Authentication and connection management are handled by the underlying SDK.
• You maintain a single connection to Ably rather than multiple connections.
• You can extend your application's functionality with custom Pub/Sub features alongside the purpose-built SDK.

When to combine SDKs

Combine a purpose-built SDK with Pub/Sub when:

• The SDK covers most of your requirements but lacks a specific feature.
• You need to build custom functionality that integrates with SDK-managed features.
• You want to publish or subscribe to custom channels alongside SDK-managed channels.

Example use cases

The following are examples where combining the Chat SDK with Pub/Sub is effective:

How it works in practice

When you initialize a Chat or Spaces client, it creates or accepts an underlying Ably Realtime client. You can use this client directly to:

• Attach to custom channels outside of SDK-managed rooms or spaces.
• Publish messages with custom event types.
• Subscribe to channels for features the SDK doesn't provide.
• Access presence on channels not managed by the SDK.

This approach lets you start with a purpose-built SDK for rapid development, then extend with Pub/Sub only where needed. You avoid rebuilding features that the SDK already handles well, while retaining the flexibility to customize your application.

Best practices

When combining SDKs with Pub/Sub:

• Use consistent authentication: Let the purpose-built SDK manage authentication and share its Realtime client rather than creating separate clients.
• Avoid duplicating SDK features: If the Chat SDK provides typing indicators, use them rather than building your own on Pub/Sub.
• Namespace your custom channels: Use a clear naming convention to distinguish custom Pub/Sub channels from SDK-managed channels.
• Consider message ordering: Messages on SDK-managed channels and custom Pub/Sub channels are independent; design your application accordingly.
• Handle connection state once: The underlying Realtime client manages connection state; don't add redundant connection handling for custom features.

Next steps

• Follow the getting started guide to start building with Ably Pub/Sub.
• Get started with Chat, Spaces, LiveObjects, LiveSync, or AI Transport.
• Explore examples to see working implementations of common use cases.
• Understand authentication before going to production.
• Review connection management for the Realtime interface.