Skip to content

Subscription API

Subscription-management interface — instantiates Topic-Brokered Event Distribution

Lets consumers register, adjust, and retire their own subscriptions through a self-serve interface, recording each in the subscription registry and governing its lifecycle.

A Subscription API is the control plane a consumer uses to declare what it wants to hear — the interface for creating, changing, and deleting subscriptions, and the registry that remembers them. It is the consumer-side mirror of the publish path: where the producer says what happened, the subscriber uses this API to say what kind of happenings it wants and where to send them. Its defining move is to make each subscription a first-class, self-managed record with a lifecycle — created on request, mutable, and eventually expired — rather than a routing rule some central team hand-edits. It never carries an event itself; it governs the bindings the delivery machinery later reads.

Example

A regional flood-warning service needs public weather alerts. Through the subscription API it registers a subscription to the severe_weather.alert topic, scoped to its state and pointed at its ingestion endpoint. The call is idempotent — retrying it does not create a duplicate — and the subscription is written to the registry with a durable flag, so alerts are held for it even during a brief outage. Weeks later the service narrows its interest to two counties by updating the same subscription; when the pilot ends, it deletes it. At no point does it negotiate with whatever upstream systems publish the alerts, and at no point does an operator touch a routing table by hand — the service owns its own wiring end to end.

How it works

  • CRUD over subscriptions — create, read, update, delete, each keyed idempotently by consumer, topic, and selector so retries and reconciliation are safe.
  • Registry of record — every live subscription is persisted with its topic, filter, delivery target, and durability, forming the authoritative set the broker routes against.
  • Lifecycle assignment — each subscription is stamped durable or ephemeral and given a lease or TTL, a renewal expectation, and an end state.
  • Reaping — leases that lapse without renewal expire, so subscriptions for consumers that have quietly disappeared do not linger forever.

Tuning parameters

  • Durable versus ephemeral default — durable subscriptions retain events across consumer downtime (at the cost of a growing backlog); ephemeral ones vanish when the consumer disconnects.
  • Lease length and renewal cadence — short leases reap dead subscriptions quickly but demand frequent heartbeats; long leases are low-maintenance but let zombies accumulate.
  • Self-serve versus approved — whether a subscription is live on request or requires sign-off, trading friction against control.
  • Selector expressiveness — how rich a filter the API accepts (it stores the predicate; evaluating it is another mechanism's job).
  • Per-consumer quota — a ceiling on how many subscriptions one consumer may hold, guarding against runaway registration.

When it helps, and when it misleads

Its strength is that consumers wire themselves up and tear themselves down without a routing bottleneck, and the registry gives the whole system one authoritative answer to who is subscribed to what. Its failure mode is subscription sprawl: durable subscriptions[1] that are never expired pile up as consumers come and go, and each abandoned one keeps the broker fanning events into a backlog nobody drains, quietly consuming storage and confusing every audit. The classic misuse is defaulting everything to durable-and-forever because it is the safe-feeling choice. The discipline is to give subscriptions leases and require renewal, so a subscription's continued existence is evidence a live consumer still wants it — not merely that no one remembered to delete it.

How it implements the components

  • subscription_registry — it maintains the authoritative store of live subscriptions, the single source of truth the routing layer consults to decide who receives an event.
  • subscription_lifecycle_rule — it assigns and enforces each subscription's durability, lease, renewal, and expiry, so subscriptions are born, maintained, and reaped by rule.

It records and governs subscriptions but does not evaluate the filter predicates they carry (filter_and_selector_rule — that's Content-Based Subscription Filter), route matched events to them (broker_routing_boundary — Topic Exchange or Event Bus), or decide who is permitted to subscribe (authorization_and_visibility_policy — that's Access-Controlled Topic).

References

[1] A durable subscription is one the broker remembers across consumer disconnections, holding matching events until the consumer returns — as opposed to an ephemeral subscription that exists only while the consumer is connected. The distinction is old (it long predates modern event buses, appearing in enterprise messaging standards) and it is the pivot on which subscription-lifecycle policy turns. ↩