This is an automated email from the ASF dual-hosted git repository.
mmerli pushed a commit to branch master
in repository https://gitbox.apache.org/repos/asf/pulsar.git
The following commit(s) were added to refs/heads/master by this push:
new ec4bb77e621 [cleanup] PIP-457: Remove support for V1 topic names and
V1 Admin API (#25275)
ec4bb77e621 is described below
commit ec4bb77e621af2fdda1c1a2aa02c04d3597f674f
Author: Matteo Merli <[email protected]>
AuthorDate: Mon Mar 9 11:11:39 2026 -0700
[cleanup] PIP-457: Remove support for V1 topic names and V1 Admin API
(#25275)
---
pip/pip-457.md | 204 +++++++++++++++++++++++++++++++++++++++++++++++++++++++++
1 file changed, 204 insertions(+)
diff --git a/pip/pip-457.md b/pip/pip-457.md
new file mode 100644
index 00000000000..2a165d9cb84
--- /dev/null
+++ b/pip/pip-457.md
@@ -0,0 +1,204 @@
+# PIP-457: Remove support for V1 topic names and V1 Admin API
+
+## Background knowledge
+
+Apache Pulsar historically supported two topic naming formats:
+
+- **V1 format**: `persistent://tenant/cluster/namespace/topic` — includes the
cluster name in the topic path
+- **V2 format**: `persistent://tenant/namespace/topic` — omits the cluster
name, making all namespaces implicitly "global"
+
+The V1 format was the original naming convention from Pulsar's early days.
PIP-10 introduced V2 topic names in Pulsar 2.0 (released June 2018) by removing
the cluster component, and PIP-11 further simplified naming with short topic
names defaulting to `persistent://public/default/`. V1 topic names have been
deprecated since Pulsar 2.0 — nearly 8 years ago at the time of this proposal.
+
+The V1 naming format also implied a separate set of Admin REST API endpoints,
Lookup endpoints, and WebSocket paths that include
`{property}/{cluster}/{namespace}` in their URL structure, as opposed to the V2
paths using `{tenant}/{namespace}`.
+
+These V1 APIs have been deprecated and hidden from the API documentation for
many years. The V2 format has been the recommended and default format since
Pulsar 2.0.
+
+## Motivation
+
+The continued presence of V1 topic name support imposes several costs on the
project:
+
+1. **Maintenance burden**: Every Admin API operation must be duplicated across
V1 and V2 endpoint classes (`v1.PersistentTopics`, `v1.NonPersistentTopics`,
`v1.Namespaces`, `v1.TopicLookup` alongside their V2 counterparts). Bug fixes
and new features touching admin APIs must account for both code paths.
+
+2. **Increased attack surface**: The V1 endpoints are hidden from
documentation but still active and routable, creating undocumented API surface
area that must be secured, tested, and maintained.
+
+3. **Code complexity in TopicName parsing**: The `TopicName` class must handle
both 3-part (V2) and 4-part (V1) name parsing, and the `isV2()` check
propagates throughout the broker, lookup, and client code.
+
+4. **WebSocket handler complexity**: WebSocket paths must support both
`/ws/producer/persistent/{property}/{cluster}/{namespace}/{topic}` (V1) and
`/ws/v2/producer/persistent/{tenant}/{namespace}/{topic}` (V2).
+
+5. **Confusion for new contributors and operators**: The existence of two
naming schemes and two sets of admin APIs creates unnecessary confusion and
cognitive overhead.
+
+6. **Test matrix expansion**: V1 paths must be covered by integration and unit
tests, expanding the test matrix without providing value to modern deployments.
+
+V1 topics have been deprecated since Pulsar 2.0, released in June 2018. With
nearly 8 years having passed and the project now on the 4.x release line, it is
time to complete this deprecation and remove V1 support entirely.
+
+## Goals
+
+### In Scope
+
+- Remove all V1 Admin REST API endpoint classes and their registrations:
+ - `org.apache.pulsar.broker.admin.v1.PersistentTopics`
+ - `org.apache.pulsar.broker.admin.v1.NonPersistentTopics`
+ - `org.apache.pulsar.broker.admin.v1.Namespaces`
+ - `org.apache.pulsar.broker.admin.v1.Clusters` (if present)
+- Remove V1 topic lookup endpoint:
+ - `org.apache.pulsar.broker.lookup.v1.TopicLookup`
+- Remove V1 WebSocket handler paths
+- Remove V1 (4-part) topic name parsing from `TopicName` and related classes
+- Remove `isV2()` method and all conditional branching based on V1 vs V2 topic
format
+- Remove `LOOKUP_PATH_V1` constant and related redirect logic
+- Remove or update all tests that exercise V1 code paths
+- Update CLI tools that may still reference V1 format
+- Log a clear error message if a client attempts to use a V1-style topic name,
to aid migration
+
+### Out of Scope
+
+- Removal of the V2 Admin API in favor of V4 (that would be a separate PIP)
+- Changes to the binary protocol wire format
+- Metadata store migration of existing V1 topic metadata (this PIP covers code
removal; data migration would be addressed separately if needed)
+
+## High Level Design
+
+The removal will be executed in a single coordinated change:
+
+1. **Admin API**: Delete the `v1` package under
`pulsar-broker/src/main/java/org/apache/pulsar/broker/admin/v1/` and remove the
registration of V1 REST resources from the broker's web server initialization.
+
+2. **Lookup**: Delete
`pulsar-broker/src/main/java/org/apache/pulsar/broker/lookup/v1/TopicLookup.java`
and remove its registration.
+
+3. **TopicName parsing**: Simplify `TopicName` to only accept the 3-part V2
format (`domain://tenant/namespace/localName`). If a 4-part name is provided,
throw a clear `IllegalArgumentException` with a message explaining V1 names are
no longer supported and how to convert.
+
+4. **WebSocket**: Remove V1 URI parsing paths from `AbstractWebSocketHandler`
and related classes.
+
+5. **Tests**: Remove or convert all V1-specific test cases. Tests that
coincidentally use V1 names should be updated to V2 format.
+
+## Detailed Design
+
+### Admin API Removal
+
+The following classes will be deleted:
+-
`pulsar-broker/src/main/java/org/apache/pulsar/broker/admin/v1/PersistentTopics.java`
+-
`pulsar-broker/src/main/java/org/apache/pulsar/broker/admin/v1/NonPersistentTopics.java`
+-
`pulsar-broker/src/main/java/org/apache/pulsar/broker/admin/v1/Namespaces.java`
+
+Their registration in the broker's Jersey/JAX-RS application configuration
will be removed.
+
+### TopicName Simplification
+
+In `pulsar-common`, the `TopicName` class will be modified:
+
+```java
+// Before: accepts both V1 (4 parts) and V2 (3 parts)
+// After: only accepts V2 (3 parts)
+private TopicName(String completeTopicName) {
+ // ... parse domain://
+ String[] parts = rest.split("/", 3); // tenant/namespace/localName
+ if (parts.length != 3) {
+ throw new IllegalArgumentException(
+ "Invalid topic name '" + completeTopicName + "'. "
+ + "Expected format: 'persistent://tenant/namespace/topic'. "
+ + "V1 topic names (with cluster component) are no longer
supported. "
+ + "Please use the V2 format without the cluster name.");
+ }
+ this.tenant = parts[0];
+ this.namespace = parts[1];
+ this.localName = parts[2];
+ // cluster field removed entirely
+}
+```
+
+The `isV2()` method and `cluster` field will be removed from `TopicName`. All
call sites that branch on `isV2()` will be simplified.
+
+The `NamespaceName` class will similarly be simplified to remove V1 support.
+
+### Lookup Simplification
+
+The `LOOKUP_PATH_V1` constant and any conditional logic choosing between V1/V2
redirect paths will be removed. Lookups will only use V2 paths.
+
+### WebSocket Simplification
+
+The `getTopic()` method in WebSocket handler classes will be simplified to
only parse V2-style URIs (`/ws/v2/...`).
+
+## Public-facing Changes
+
+### REST API
+
+The following REST API paths will be **removed**:
+
+**Persistent Topics (V1)**:
+- `GET /admin/persistent/{property}/{cluster}/{namespace}` — list topics
+- `GET/PUT/DELETE
/admin/persistent/{property}/{cluster}/{namespace}/{topic}/...` — all topic
operations
+- `GET/PUT/DELETE
/admin/persistent/{property}/{cluster}/{namespace}/partitioned` — partitioned
topic operations
+
+**Non-Persistent Topics (V1)**:
+- `GET /admin/non-persistent/{property}/{cluster}/{namespace}` — list topics
+- `GET/PUT/DELETE
/admin/non-persistent/{property}/{cluster}/{namespace}/{topic}/...` — all topic
operations
+
+**Namespaces (V1)**:
+- `GET/PUT/DELETE /admin/namespaces/{property}/{cluster}/{namespace}` — all
namespace operations
+
+**Lookup (V1)**:
+- `GET
/lookup/v2/destination/{topic-domain}/{property}/{cluster}/{namespace}/{topic}`
— topic lookup
+
+### Binary Protocol
+
+No changes to the binary protocol.
+
+### Configuration
+
+No new configuration. The broker configuration key `allowV1Topics` may be
considered for a transitional release but is **not** proposed here — the
removal is clean and complete.
+
+### CLI
+
+`pulsar-admin` and `pulsar-client` CLI tools will only accept V2 topic names.
Passing a V1 topic name will produce a clear error message with migration
guidance.
+
+### Metrics
+
+No metrics changes.
+
+## Monitoring
+
+Operators should monitor for client errors after the upgrade. Clients
attempting to use V1 topic names will receive clear error responses (HTTP 404
for V1 admin paths, or client-side `IllegalArgumentException` for V1 topic
names).
+
+## Security Considerations
+
+This change reduces the API attack surface by removing undocumented but active
REST endpoints. No new security considerations are introduced.
+
+## Backward & Forward Compatibility
+
+### Upgrade
+
+This is a **breaking change** for any deployment still using V1 topic names or
V1 Admin API paths.
+
+Before upgrading to the version containing this change, operators must:
+1. Ensure all topic names in use follow the V2 format
(`persistent://tenant/namespace/topic`)
+2. Ensure all Admin API clients use V2 endpoints (`/admin/v2/...`)
+3. Ensure all WebSocket clients use V2 paths (`/ws/v2/...`)
+
+The V1 format has been deprecated since Pulsar 2.0, released in June 2018 —
nearly 8 years ago. Any deployment that has been maintained on a supported
Pulsar version should already be using V2 format exclusively.
+
+### Downgrade / Rollback
+
+Rolling back to a prior version that supports V1 topic names will work without
issues, as no data format changes are involved.
+
+### Geo-Replication
+
+No impact. Geo-replication already uses V2 topic names. The cluster component
in V1 topic names was originally related to replication configuration but has
been decoupled since V2 was introduced.
+
+## General Notes
+
+### Related PIPs
+- PIP-10: Remove cluster from topic name (introduced V2 naming)
+- PIP-11: Short topic name (further simplified topic naming)
+- PIP-48: Proposed V4 admin API (future direction for admin APIs)
+
+### Migration Guide
+
+For any users who may still be using V1 topic names, the migration is
straightforward:
+
+| V1 Format | V2 Format |
+|---|---|
+| `persistent://my-tenant/my-cluster/my-namespace/my-topic` |
`persistent://my-tenant/my-namespace/my-topic` |
+| `/admin/persistent/my-tenant/my-cluster/my-namespace` |
`/admin/v2/persistent/my-tenant/my-namespace` |
+| `/ws/producer/persistent/my-tenant/my-cluster/my-ns/my-topic` |
`/ws/v2/producer/persistent/my-tenant/my-ns/my-topic` |
+
+Simply remove the cluster component from the topic name path.
+
