[
https://issues.apache.org/jira/browse/UNOMI-904?page=com.atlassian.jira.plugin.system.issuetabpanels:all-tabpanel
]
Serge Huber reassigned UNOMI-904:
---------------------------------
Assignee: Serge Huber
> 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
> Assignee: Serge Huber
> Priority: Major
> 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)
