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[n1] 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).
Related¶
- Instantiates: Topic-Brokered Event Distribution — it is the consumer's entry point for declaring interest.
- Sibling mechanisms: Webhook Subscription · Content-Based Subscription Filter · Access-Controlled Topic · Subscription Health Dashboard · Consumer Group
Editorial Notes¶
Form Classification¶
Form family: Control, Automation & Runtime
Rationale: Subscription API operates as a live operational control that automatically routes, enforces, adapts, or responds during execution because it lets consumers register, adjust, and retire their own subscriptions through a self-serve interface, recording each in the subscription registry and governing its lifecycle.
Independent corroboration: The frozen evidence defines Subscription API as 'Lets consumers register, adjust, and retire their own subscriptions through a self-serve interface, recording each in the subscription registry and governing its lifecycle', so its operative form is Control, Automation & Runtime.
Nearest alternative: Monitoring, Sensing & Alerting — Subscription API includes features of ongoing observation, sensing, or alerting that detects and surfaces state without itself executing the response, but its defining operation is a live operational control that automatically routes, enforces, adapts, or responds during execution.
Review outcome: Independent reviewer agreement; medium confidence.
Origin Attribution¶
Primary origin: Computer Science & Software Engineering
Origin pattern: Single lineage
Present-day reach: Universal
Rationale: Self-service registration and lifecycle control are subscription API design.
Related originating lineages:
- Engineering & Design — Engineering design, reliability, and systems-safety practice supplies a parallel or contributing lineage for the mechanism's defining operation: lets consumers register, adjust, and retire their own subscriptions through a self-serve interface, recording each in the subscription registry and governing its lifecycle.
- Human-Computer Interaction — Consumers manage preferences.
Review resolution: The blind reviewers agree that computer_science is the primary origin and differ only on alternate origin disagreement, domain reach disagreement. I preserve every independently explained alternate from both records rather than imposing a numeric cap. I retain single_lineage because the combined evidence shows one traceable formative lineage. The broader reach of universal records portability separately from historical provenance; encyclopedia_synthesis=false preserves the affirmative synthesis judgment where either reviewer identified one.
Review outcome: Reconciled after independent review; high confidence.
Notes¶
[n1] 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. ↩