Refactor and enhance API publishing flow

Overview

This issue tracks the refactoring and enhancement of the entire API publishing flow to improve structure, maintainability, and functionality.

Background

During review of PR #136, several opportunities for improvement in the API publishing flow were identified. Rather than addressing these piecemeal, this issue consolidates the effort to re-implement and refactor the publishing flow comprehensively.

Scope

1. Gateway UUID Validation

• Current validation in APIPublication.Validate() requires SandboxGatewayUUID and ProductionGatewayUUID for all statuses
• Should only require gateway UUIDs when publication status is Published
• This blocks creation of records in unpublished, publishing, or failed states without gateway mappings

2. Publishing Flow Architecture

• Review and refactor the end-to-end publishing workflow
• Improve state management and transitions
• Enhance error handling and recovery mechanisms
• Optimize validation logic throughout the flow

3. Code Structure and Maintainability

• Improve separation of concerns
• Enhance testability
• Add comprehensive validation at appropriate layers
• Document the publishing lifecycle clearly

References

• PR #136: https://github.com/wso2/api-platform/pull/136
• Original discussion: https://github.com/wso2/api-platform/pull/136#discussion_r2514693248

Acceptance Criteria

• Gateway UUID validation is conditional based on publication status
• Publishing flow is well-structured and maintainable
• Comprehensive tests cover the refactored flow
• Documentation describes the publishing lifecycle and validation rules
• Error handling provides clear, actionable feedback