Serge Huber created UNOMI-904:
---------------------------------
Summary: V2 API Compatibility mode
Key: UNOMI-904
URL: https://issues.apache.org/jira/browse/UNOMI-904
Project: Apache Unomi
Issue Type: Sub-task
Components: unomi(-core)
Affects Versions: unomi-3.0.0
Reporter: Serge Huber
Fix For: unomi-3.0.0
h2. Summary
Enable client applications designed for Apache Unomi V2 to work with Unomi V3
without requiring immediate code changes or authentication modifications.
h2. Problem Statement
h3. Background
Apache Unomi V3 introduces comprehensive multi-tenancy support with a new
tenant-based authentication model using API keys. This represents a fundamental
architectural change from V2's system administrator authentication approach.
h3. Current Situation
* Organizations running Unomi V2 have multiple client applications using V2
authentication patterns
* V2 clients cannot connect to Unomi V3 without authentication code changes
* All client applications must be updated simultaneously to migrate to V3
* No gradual migration path exists for organizations with multiple applications
* Migration requires immediate code changes across all client applications
h3. Business Impact
* *Service Disruption Risk*: Organizations must update all client applications
before migrating to V3
* *Migration Complexity*: No ability to migrate applications incrementally
* *Downtime Requirements*: All applications must be updated and tested
simultaneously
* *Resource Constraints*: Organizations need to allocate significant
development resources for immediate migration
* *Testing Overhead*: All client applications must be tested with new
authentication before migration
h3. Technical Challenges
* V2 clients use system administrator authentication (karaf/karaf) for private
endpoints
* V2 clients send public endpoints (like `/context.json`) without authentication
* V2 clients use IP + X-Unomi-Peer headers for protected events
* V3 requires tenant-specific API keys for all operations
* V3 enforces tenant context for all data operations
h3. Migration Barriers
* *Authentication Model Mismatch*: V2 and V3 use completely different
authentication approaches
* *No Backward Compatibility*: V3 does not support V2 authentication patterns
* *All-or-Nothing Migration*: Cannot migrate applications one at a time
* *Testing Complexity*: Cannot test V3 migration with existing V2 clients
* *Rollback Difficulties*: No easy way to revert if migration issues occur
h2. User Stories
h3. As an Organization with Multiple V2 Client Applications
I want to migrate to Unomi V3 gradually so that I can:
* Test V3 with my existing V2 applications before making changes
* Migrate applications one at a time to minimize risk
* Maintain service continuity during the migration process
* Validate V3 functionality with real V2 client behavior
h3. As a System Administrator
I want to enable V2 compatibility in Unomi V3 so that I can:
* Deploy V3 without immediately updating all client applications
* Test V3 in production with existing V2 clients
* Gradually migrate applications over time
* Maintain operational stability during migration
h3. As a Developer
I want to test V3 compatibility with V2 clients so that I can:
* Verify V3 works with existing V2 authentication patterns
* Test V3 features without modifying client code
* Validate migration scripts and data transformation
* Ensure no breaking changes in API behavior
h2. Acceptance Criteria
h3. Functional Requirements
* [ ] V2 client applications can connect to Unomi V3 without code changes
* [ ] V2 authentication patterns work with Unomi V3
* [ ] Public endpoints (like `/context.json`) work without authentication
* [ ] Private endpoints work with system administrator authentication
* [ ] Protected events work with IP + X-Unomi-Peer authentication
* [ ] V2 clients can send events and retrieve context data
* [ ] V2 clients can access profiles and segments
* [ ] V2 clients can manage rules and schemas
h3. Migration Requirements
* [ ] Organizations can migrate to V3 without updating all client applications
* [ ] V2 clients work immediately after V3 deployment
* [ ] Gradual migration of applications is supported
* [ ] V2 compatibility can be enabled/disabled via configuration
* [ ] V2 compatibility mode is temporary and can be removed after migration
h3. Testing Requirements
* [ ] Existing V2 test suites work with Unomi V3 when V2 compatibility mode is
activated
* [ ] V2 client applications can be tested against V3
* [ ] Migration testing can be performed with real V2 clients
* [ ] V2 compatibility mode can be tested independently
h2. Business Value
* *Reduced Migration Risk*: Organizations can test V3 before committing to full
migration
* *Gradual Migration*: Applications can be migrated incrementally over time
* *Service Continuity*: No service disruption during V3 migration
* *Reduced Development Effort*: Organizations can migrate at their own pace
* *Improved Testing*: Real V2 clients can be used to test V3 functionality
h2. Success Metrics
* V2 client applications work with Unomi V3 without modifications
* Organizations can successfully migrate from V2 to V3
* Migration process does not cause service disruptions
* V2 compatibility mode enables successful V3 adoption
h2. Dependencies
* Unomi V3 multi-tenant architecture
* V2 authentication patterns and behaviors
* Existing V2 client applications
* Migration scripts for V2 to V3 data transformation
--
This message was sent by Atlassian Jira
(v8.20.10#820010)
