From 11e2c7dbfeef14c87586a48bb363cabf0d3e3aaf Mon Sep 17 00:00:00 2001 From: LakshmipriyaPurushan Date: Mon, 17 Nov 2025 11:17:21 +0000 Subject: [PATCH 01/23] RDKCLOUD-190, RDKCLOUD-191: Generate an Overview documentation for xconf Reason for change: Generate an Overview documentation for xconf as well as Generate an API documentation for xconfadmin Test Procedure: Build should pass Risks: Low Signed-off-by:Lakshmipriya_Purushan@comcast.com --- docs/overview.md | 677 ++++++++ docs/tagging_api_documentation.md | 519 +++++++ docs/xconfadmin_API_Documentation.md | 2153 ++++++++++++++++++++++++++ 3 files changed, 3349 insertions(+) create mode 100644 docs/overview.md create mode 100644 docs/tagging_api_documentation.md create mode 100644 docs/xconfadmin_API_Documentation.md diff --git a/docs/overview.md b/docs/overview.md new file mode 100644 index 0000000..8e39045 --- /dev/null +++ b/docs/overview.md @@ -0,0 +1,677 @@ +# XConf System Overview + +## Table of Contents +- [Overview](#overview) +- [System Architecture](#system-architecture) +- [Core Components](#core-components) +- [Process Flow Diagrams](#process-flow-diagrams) +- [Use Cases](#use-cases) +- [API Overview](#api-overview) +- [Configuration Management](#configuration-management) +- [Deployment Architecture](#deployment-architecture) +- [Security Model](#security-model) +- [Getting Started](#getting-started) + +## Overview + +XConf is a comprehensive configuration management platform designed for RDK (Reference Design Kit) devices. It provides centralized control over device configurations, firmware updates, telemetry settings, and feature management across large-scale RDK deployments. The system is built with Go and follows a microservices architecture with three main components working together to deliver a complete configuration management solution. + +### Key Features + +- **Centralized Configuration Management**: XConf serves as a single point of control for all device configurations across large-scale RDK deployments. This unified approach eliminates configuration fragmentation and ensures consistency across thousands of devices in the field, providing operators with a comprehensive view of their entire device ecosystem. + +- **Firmware Management**: The platform enables operators to control firmware distribution and updates with sophisticated canary deployment strategies. This includes percentage-based rollouts, device cohort targeting, and emergency rollback procedures to minimize risk during firmware updates while ensuring rapid deployment of security patches and feature enhancements. + +- **Telemetry Services**: XConf manages comprehensive telemetry profiles and data collection policies, allowing operators to configure what data is collected, how frequently it's gathered, and where it's uploaded. This enables data-driven insights into device performance and user behavior patterns while maintaining privacy compliance and optimizing bandwidth usage. + +- **Device Control Manager (DCM)**: The DCM component handles critical device control settings and log upload policies, providing granular control over device behavior, log collection schedules, and diagnostic data management. This ensures proper device operation and facilitates troubleshooting when issues arise in production environments. + +- **Feature Management (RFC)**: Through the RDK Feature Control system, operators can control feature flags and rules with priority-based evaluation, enabling safe feature rollouts and A/B testing scenarios. Features can be activated for specific device cohorts or gradually rolled out using percentage-based distribution with real-time monitoring and rollback capabilities. + +- **Authentication and Authorization**: Robust security mechanisms provide JWT-based authentication with comprehensive role-based access control, ensuring that only authorized personnel can modify configurations. All changes are properly audited and tracked, maintaining complete operational transparency and compliance requirements. + +- **RESTful APIs**: The system exposes comprehensive RESTful APIs for all operations, enabling programmatic access and integration with existing operational tools and workflows. This API-first approach supports automation and custom tooling development while maintaining consistent interface standards across all components. + +- **Metrics and Monitoring**: Built-in observability capabilities include Prometheus metrics collection and OpenTelemetry distributed tracing support, providing complete visibility into system performance and operational health across all components. This enables proactive monitoring and rapid issue resolution. + +- **High Availability**: The platform achieves operational resilience through distributed locking mechanisms and multi-level caching strategies that enable scalable operations across multiple data centers while maintaining data consistency and system reliability with sub-second response times. + +## System Architecture + +The XConf system follows a three-tier architecture with clear separation of responsibilities: + +```mermaid +graph TB + subgraph "Client Layer" + RDK[RDK Devices
Config Requests] + WebUI[Web UI
User Interface] + ExtAPI[External APIs
Admin Operations] + end + + subgraph "Service Layer" + WebConfig[XConf WebConfig
Port: 9000
Device API] + UIServer[XConf UI Server
Port: 8081
Web Interface] + Admin[XConf Admin
Port: 9001
Management API] + end + + subgraph "Data Layer" + Cassandra[(Cassandra DB
Primary Storage)] + Redis[(Redis Cache
High Performance)] + end + + subgraph "External Services" + SAT[SAT Service
Auth Tokens] + IDP[Identity Provider
User Auth] + Prometheus[Prometheus
Metrics] + OTEL[OTEL Collector
Tracing] + end + + %% Client to Service connections + RDK -->|Configuration Queries| WebConfig + WebUI -->|User Interface| UIServer + ExtAPI -->|Admin Operations| Admin + + %% Service to Service connections + UIServer -->|Proxy Requests| Admin + + %% Service to Data connections + WebConfig --> Cassandra + WebConfig --> Redis + Admin --> Cassandra + Admin --> Redis + + %% Service to External connections + WebConfig --> SAT + Admin --> SAT + Admin --> IDP + WebConfig --> Prometheus + Admin --> Prometheus + WebConfig --> OTEL + Admin --> OTEL + + %% Styling for better contrast on white background + classDef clientLayer fill:#e1f5fe,stroke:#01579b,stroke-width:2px,color:#000 + classDef serviceLayer fill:#f3e5f5,stroke:#4a148c,stroke-width:2px,color:#000 + classDef dataLayer fill:#e8f5e8,stroke:#1b5e20,stroke-width:2px,color:#000 + classDef externalLayer fill:#fff3e0,stroke:#e65100,stroke-width:2px,color:#000 + + class RDK,WebUI,ExtAPI clientLayer + class WebConfig,UIServer,Admin serviceLayer + class Cassandra,Redis dataLayer + class SAT,IDP,Prometheus,OTEL externalLayer +``` + +### Architecture Principles +- **Microservices Design**: Each component has a specific responsibility +- **Stateless Services**: All services are stateless for horizontal scalability +- **Event-Driven**: Asynchronous processing for configuration changes +- **Security First**: Multiple layers of authentication and authorization +- **Observability**: Built-in metrics, logging, and distributed tracing + +## Core Components + +### 1. XConf Admin +**Purpose**: Administrative backend service for configuration management + +**Key Capabilities**: +- Configuration CRUD operations (firmware, DCM, telemetry, RFC) +- Rule-based configuration management with priority handling +- User authentication and authorization +- Change management and audit logging +- API gateway for administrative functions + +**Main Modules**: +- `adminapi/`: REST API handlers and routing +- `auth/`: Authentication and authorization services +- `firmware/`: Firmware configuration management +- `dcm/`: Device Control Manager settings +- `telemetry/`: Telemetry profile management +- `rfc/`: RDK Feature Control management +- `queries/`: Query and reporting services + +### 2. XConf WebConfig +**Purpose**: Data service for RDK devices to retrieve configurations + +**Key Capabilities**: +- High-performance configuration delivery to RDK devices +- Rule engine for dynamic configuration evaluation +- Firmware version determination and distribution control +- Telemetry and DCM settings delivery +- Health checks and diagnostics + +**Main Modules**: +- `dataapi/`: Device-facing API endpoints +- `rulesengine/`: Configuration rule evaluation +- `db/`: Database abstraction and caching +- `security/`: Request validation and security +- `tracing/`: Distributed tracing implementation + +### 3. XConf UI +**Purpose**: Web-based user interface for system administration + +**Key Capabilities**: +- Interactive web interface for configuration management +- Proxy service to XConf Admin backend +- Static asset serving (HTML, CSS, JavaScript) +- User session management + +**Main Modules**: +- `app/`: Angular-based web application +- `server/`: Go-based proxy server +- `templates/`: HTML templates + +## Process Flow Diagrams + +### Device Configuration Request Flow + +```mermaid +sequenceDiagram + participant RDK as RDK Device + participant WC as XConf WebConfig + participant Cache as Cache Layer + participant DB as Database + + RDK->>WC: GET /xconf/swu/stb?eStbMac=...&model=... + + WC->>Cache: Check cache for device config + + alt Cache Hit + Cache-->>WC: Return cached config + else Cache Miss + Cache-->>WC: Config not found + WC->>DB: Query config rules + DB-->>WC: Rules & settings + + Note over WC: Evaluate rules
Apply security
Generate JSON + + WC->>Cache: Store computed config + end + + WC-->>RDK: Configuration Response + + Note over RDK,WC: Response includes firmware version,
download URL, DCM settings, etc.
Device parameters include MAC address,
model, environment, etc. +``` + +### Administrative Configuration Update Flow + +```mermaid +sequenceDiagram + participant Admin as Administrator + participant UI as XConf UI + participant API as XConf Admin + participant DB as Database + participant Cache as Cache Layer + + Admin->>UI: Update firmware rule + UI->>API: POST /xconfAdminService/firmwarerule + + Note over API: Validate auth & rule + + API->>DB: Store updated rule + API->>Cache: Invalidate cache entries + + API-->>UI: Confirmation response + UI-->>Admin: Success notification + + Note over Admin,Cache: Next device request will fetch
updated configuration from refreshed cache +``` + +### Feature Flag Management Flow + +```mermaid +sequenceDiagram + participant Admin as Administrator + participant API as XConf Admin + participant RDK as RDK Device + participant WC as XConf WebConfig + + Admin->>API: Create RFC feature rule + + Note over API: Validate rule conditions
& set priority + + RDK->>WC: Request feature settings + + Note over WC: Evaluate RFC rules by priority
Apply percentage-based rollout + + WC-->>RDK: Feature configuration + + Note over RDK: Apply settings based on config + + Note over Admin,RDK: Flow Summary:
1. Administrator creates RFC feature rules with conditions and rollout percentages
2. RDK devices periodically request feature settings from XConf WebConfig
3. WebConfig evaluates rules by priority and applies percentage-based distribution
4. Devices receive feature configuration and apply settings accordingly +``` + +## Use Cases + +The XConf platform supports diverse operational scenarios across different organizational roles and responsibilities. Each use case demonstrates the platform's capability to address specific configuration management challenges in RDK device deployments. + +### Use Case 1: Firmware Management +**Primary Actors**: Operations Team, DevOps Team +**Supporting Systems**: XConf Admin, XConf WebConfig, Device Fleet + +**Scenario**: Operations teams need to roll out new firmware versions to thousands of RDK devices while minimizing risk and ensuring system stability during the deployment process. + +**Process Flow**: +1. **Upload Firmware Configuration**: Operations team uploads firmware version metadata including download URLs, checksums, and compatibility information through XConf Admin interface +2. **Create Deployment Rules**: Define targeting rules based on device models, environments, and partner configurations with conditional logic +3. **Configure Canary Strategy**: Implement percentage-based rollout starting with 1% of devices, gradually increasing to full deployment +4. **Monitor Deployment Progress**: Track firmware adoption rates, device health metrics, and rollback triggers through real-time dashboards +5. **Emergency Response**: Execute rapid rollback procedures if issues are detected during deployment + +**Expected Outcomes**: Controlled firmware distribution with minimized risk, comprehensive deployment visibility, and rapid issue resolution capabilities. + +### Use Case 2: Device Control Manager (DCM) Configuration +**Primary Actors**: Support Team, Operations Team +**Supporting Systems**: XConf Admin, Device Diagnostic Systems + +**Scenario**: Support teams require granular control over device log collection, diagnostic data uploads, and device behavior parameters to facilitate troubleshooting and maintain operational visibility. + +**Process Flow**: +1. **Define Log Upload Policies**: Configure log collection schedules, retention policies, and upload destinations based on device types and support requirements +2. **Configure Device Settings**: Set device behavior parameters including reboot schedules, diagnostic intervals, and maintenance windows +3. **Create Conditional Formulas**: Implement rule-based logic for dynamic device control based on device health, network conditions, and operational requirements +4. **Deploy Settings**: Push DCM configurations to targeted device populations with validation and rollback capabilities +5. **Monitor Collection**: Track log upload success rates, diagnostic data quality, and device compliance with configured policies + +**Expected Outcomes**: Automated log collection, improved troubleshooting capabilities, and enhanced device operational visibility. + +### Use Case 3: Feature Flag Control (RFC) +**Primary Actors**: Product Team, QA Team +**Supporting Systems**: XConf Admin, XConf WebConfig, Feature Management System + +**Scenario**: Product teams need to implement safe feature rollouts, conduct A/B testing, and manage experimental features across device populations with precise targeting and rollback capabilities. + +**Process Flow**: +1. **Create Feature Control Rules**: Define feature activation conditions based on device characteristics, user segments, and deployment criteria +2. **Configure Rollout Strategy**: Implement percentage-based feature distribution with gradual increase and statistical validation +3. **Set Feature Parameters**: Configure feature-specific settings, default values, and behavioral parameters for targeted device groups +4. **Monitor Feature Performance**: Track feature adoption rates, user engagement metrics, and system performance impact +5. **Optimize and Scale**: Adjust feature parameters based on performance data and scale successful features to broader device populations + +**Expected Outcomes**: Safe feature experimentation, data-driven feature decisions, and controlled feature deployment with rapid iteration capabilities. + +### Use Case 4: Telemetry Management +**Primary Actors**: Analytics Team, Product Team +**Supporting Systems**: XConf Admin, Data Collection Infrastructure, Analytics Platform + +**Scenario**: Analytics teams require comprehensive telemetry data collection from device populations to support product insights, performance optimization, and business intelligence initiatives. + +**Process Flow**: +1. **Define Collection Profiles**: Configure telemetry metrics, collection intervals, and data schemas based on analytical requirements +2. **Target Device Segments**: Create targeting rules for different device populations, user segments, and geographical regions +3. **Configure Upload Schedules**: Set data upload frequencies, bandwidth optimization, and privacy compliance parameters +4. **Validate Data Quality**: Implement data validation rules, quality checks, and error handling procedures +5. **Generate Analytics Reports**: Process collected telemetry data for business insights, performance optimization, and product development + +**Expected Outcomes**: Comprehensive device insights, data-driven product decisions, and optimized user experience based on telemetry analytics. + +### Use Case 5: Environment Configuration Management +**Primary Actors**: DevOps Team, Infrastructure Team +**Supporting Systems**: XConf Admin, CI/CD Pipeline, Environment Management Tools + +**Scenario**: DevOps teams need to maintain configuration consistency across development, staging, and production environments while enabling seamless configuration promotion and environment-specific customizations. + +**Process Flow**: +1. **Define Environment Rules**: Create environment-specific configuration rules with inheritance patterns and override capabilities +2. **Configure Version Management**: Implement configuration versioning with promotion workflows and rollback procedures +3. **Enforce Policy Compliance**: Set automated policy validation, compliance checks, and approval workflows for configuration changes +4. **Promote Configurations**: Execute seamless configuration promotion from development through staging to production environments +5. **Monitor Configuration Drift**: Track configuration differences across environments and implement drift detection and correction + +**Expected Outcomes**: Consistent multi-environment configuration management, streamlined deployment workflows, and reduced configuration-related issues. + +### Use Case 6: Real-time Device Configuration +**Primary Actors**: RDK Devices, Automated Systems +**Supporting Systems**: XConf WebConfig, Device Management Platform, Network Infrastructure + +**Scenario**: RDK devices automatically request and receive configuration updates, apply settings based on their characteristics, and report status back to the platform for monitoring and compliance verification. + +**Process Flow**: +1. **Request Configurations**: Devices periodically query XConf WebConfig for current configuration updates based on device parameters +2. **Receive Targeted Settings**: Platform delivers device-specific configurations including firmware versions, feature settings, and operational parameters +3. **Apply Configuration Changes**: Devices validate and apply received configurations with appropriate error handling and rollback capabilities +4. **Report Status Updates**: Devices provide feedback on configuration application success, system health, and operational status +5. **Maintain Compliance**: Continuous monitoring ensures devices maintain compliance with current configuration policies + +**Expected Outcomes**: Automated device configuration management, real-time compliance monitoring, and seamless configuration distribution across device populations. + +### Use Case 7: System Monitoring and Observability +**Primary Actors**: Operations Team, Support Team, DevOps Team +**Supporting Systems**: Prometheus, OTEL Collector, Monitoring Dashboards, Alert Management + +**Scenario**: Cross-functional teams require comprehensive monitoring of system health, deployment progress, performance metrics, and operational status through integrated dashboards and proactive alerting mechanisms. + +**Process Flow**: +1. **Configure Monitoring Infrastructure**: Set up comprehensive metrics collection, distributed tracing, and log aggregation across all system components +2. **Create Performance Dashboards**: Implement real-time dashboards showing system health, device connectivity, and configuration distribution metrics +3. **Define Alert Policies**: Configure intelligent alerting for system anomalies, performance degradation, and operational issues +4. **Track Deployment Progress**: Monitor configuration rollouts, feature adoption rates, and deployment success metrics +5. **Investigate and Resolve Issues**: Use integrated monitoring data for rapid issue identification, root cause analysis, and resolution tracking + +**Expected Outcomes**: Proactive system monitoring, rapid issue detection and resolution, and comprehensive operational visibility across the entire XConf platform. + +## API Overview + +### XConf Admin API (`/xconfAdminService`) +**Authentication**: JWT tokens or session-based authentication +**Base URL**: `http://host:9001/xconfAdminService` + +**Key Endpoints**: +- `GET/POST/PUT/DELETE /firmwareconfig` - Firmware configuration management +- `GET/POST/PUT/DELETE /firmwarerule` - Firmware rule management +- `GET/POST/PUT/DELETE /dcm/formula` - DCM formula management +- `GET/POST/PUT/DELETE /telemetry/profile` - Telemetry profile management +- `GET/POST/PUT/DELETE /rfc/feature` - Feature rule management +- `GET /queries/environments` - Environment queries +- `POST /auth/basic` - Basic authentication +- `GET /provider` - Authentication provider info + +### XConf WebConfig API (`/xconf`) +**Authentication**: Device-based validation +**Base URL**: `http://host:9000/xconf` + +**Key Endpoints**: +- `GET /swu/stb` - Firmware configuration for STB devices +- `GET /loguploader/getSettings` - Log upload settings +- `GET /rfc/feature/getSettings` - Feature settings +- `GET /telemetry/getTelemetryProfiles` - Telemetry profiles +- `GET /dcm/getSettings` - DCM settings + +### Request/Response Examples + +**Device Firmware Request**: +```bash +GET /xconf/swu/stb?eStbMac=AA:BB:CC:DD:EE:FF&model=MODEL_X&env=PROD +``` + +**Firmware Response**: +```json +{ + "firmwareVersion": "2.1.0", + "firmwareDownloadURL": "https://firmware.example.com/firmware-2.1.0.bin", + "firmwareFilename": "firmware-2.1.0.bin", + "rebootImmediately": false, + "forceHttp": false +} +``` + +## Configuration Management + +XConf utilizes HOCON (Human-Optimized Config Object Notation) configuration files that provide comprehensive control over all system components. The platform supports three distinct configuration profiles optimized for different operational responsibilities. + +### Configuration Architecture + +```mermaid +graph TB + subgraph "Configuration Sources" + AdminConf[XConf Admin Config
xconfadmin.conf] + WebConfigConf[XConf WebConfig Config
xconfwebconfig.conf] + UIConf[XConf UI Config
xconfui.conf] + end + + subgraph "Configuration Categories" + ServerConfig[Server Configuration
• Port bindings
• Timeouts
• Metrics] + ServiceConfig[Service Integration
• SAT Authentication
• External APIs
• Feature toggles] + DataConfig[Data Layer
• Cassandra clusters
• Cache settings
• Connection pools] + SecurityConfig[Security Settings
• JWT tokens
• TLS certificates
• Authentication] + end + + subgraph "Runtime Environment" + EnvVars[Environment Variables
• SAT_CLIENT_ID
• DATABASE_PASSWORD
• SECURITY_TOKEN_KEY] + Deployment[Deployment Context
• Development
• Staging
• Production] + end + + AdminConf --> ServerConfig + AdminConf --> ServiceConfig + AdminConf --> DataConfig + AdminConf --> SecurityConfig + + WebConfigConf --> ServerConfig + WebConfigConf --> ServiceConfig + WebConfigConf --> DataConfig + + UIConf --> ServerConfig + UIConf --> ServiceConfig + + EnvVars --> ServiceConfig + EnvVars --> SecurityConfig + Deployment --> ServiceConfig + + %% Styling + classDef configSource fill:#e3f2fd,stroke:#0277bd,stroke-width:2px,color:#000 + classDef configCategory fill:#f3e5f5,stroke:#6a1b9a,stroke-width:2px,color:#000 + classDef runtime fill:#e8f5e8,stroke:#2e7d32,stroke-width:2px,color:#000 + + class AdminConf,WebConfigConf,UIConf configSource + class ServerConfig,ServiceConfig,DataConfig,SecurityConfig configCategory + class EnvVars,Deployment runtime +``` + +### XConf Admin Configuration + +**Primary Responsibilities**: Administrative backend operations, user authentication, and configuration management workflows. + +**Key Configuration Areas**: +- **Service Integration**: Comprehensive external service connections including SAT authentication, Identity Provider (IDP), device services, account management, and tagging systems +- **Canary Management**: Advanced deployment controls with timezone support, percentage-based rollouts, and partner-specific configurations +- **Authentication Framework**: JWT-based security with configurable token validation and role-based access control +- **Cache Strategy**: Multi-level caching with configurable refresh cycles, distributed locking mechanisms, and performance optimization +- **Database Operations**: Cassandra cluster management with SSL support, connection pooling, and query optimization settings +- **Tracing & Observability**: OpenTelemetry integration with configurable endpoints and distributed tracing capabilities + +**Notable Features**: +- Supports 20+ external service integrations with individual timeout and retry configurations +- Configurable canary deployment windows with timezone awareness +- Advanced distributed locking for concurrent operations +- Comprehensive audit logging and security token management + +### XConf WebConfig Configuration + +**Primary Responsibilities**: High-performance device-facing API operations and configuration delivery optimization. + +**Key Configuration Areas**: +- **Performance Optimization**: Enhanced caching strategies with group service integration, cache expiration policies, and connection pooling +- **Device Integration**: Specialized device service connections with model-specific configurations and validation rules +- **Feature Toggles**: Granular control over RFC features, firmware penetration metrics, and experimental capabilities +- **Security Enhancements**: Device-specific authentication, token management for firmware delivery, and protocol-based security controls +- **Data Processing**: Advanced configuration preprocessing, IP address parsing, and network mask management +- **Metrics Collection**: Device interaction metrics, model-based request tracking, and performance monitoring + +**Notable Features**: +- Device-optimized caching with 4-hour refresh cycles for group services +- Security token integration for firmware download protection +- Advanced IP address processing with IPv4/IPv6 network mask support +- RFC precooking capabilities for improved response times +- Model-specific feature enablement for targeted device populations + +### XConf UI Configuration + +**Primary Responsibilities**: Web-based administration interface and proxy service management. + +**Key Configuration Areas**: +- **Proxy Architecture**: Streamlined configuration for backend service integration through XConf Admin API +- **Web Server Settings**: Port configuration, static asset management, and web root directory specification +- **Logging Framework**: Structured logging with file-based output and caller information tracking +- **Development Support**: Simplified configuration for development environments and debugging capabilities + +**Notable Features**: +- Lightweight configuration focused on web interface requirements +- Automatic proxy routing to XConf Admin backend services +- Development-friendly logging with detailed caller information +- Minimal external dependencies for rapid deployment + +### Configuration Management Framework + +**Environment Variable Integration**: The platform leverages secure environment variable injection for sensitive configuration parameters including SAT_CLIENT_ID and SAT_CLIENT_SECRET for service-to-service authentication credentials, DATABASE_USER and DATABASE_PASSWORD for Cassandra database authentication, and SECURITY_TOKEN_KEY for JWT token signing and validation operations. + +**Configuration Validation & Processing**: XConf implements comprehensive HOCON format validation with nested object support, automatic environment variable substitution with intelligent default fallbacks, proactive service dependency validation and health checking mechanisms, and real-time configuration drift detection with automated alerting capabilities to ensure operational consistency. + +**Multi-Environment Deployment Patterns**: The system supports distinct deployment configurations optimized for different operational contexts. Development environments utilize local configuration profiles with disabled external services and enhanced debug logging for rapid development cycles. Staging environments implement production-like configurations with dedicated test service endpoints and comprehensive monitoring integration for pre-production validation. Production deployments feature full external service integration with performance-optimized settings and enterprise-grade security hardening measures. + +**Advanced Rule Engine & Logic**: XConf's configuration engine supports sophisticated conditional configuration mechanisms using complex boolean expressions for environment-specific settings, priority-based evaluation systems with hierarchical configuration override capabilities, temporal controls enabling time-based configuration activation and automated feature scheduling, and percentage distribution algorithms providing gradual rollout capabilities with statistical distribution controls for safe deployment practices. + +**Comprehensive Configuration Scope**: The platform manages diverse configuration types including firmware management systems for version control and deployment strategies, DCM policies governing log collection schedules and device behavior parameters, RFC features enabling feature flag management and A/B testing configurations, telemetry profiles defining data collection policies and analytics configurations, and security policies establishing authentication requirements and access control matrices across all system components. + +## Deployment Architecture + +XConf's production deployment architecture follows enterprise-grade patterns with multiple layers of redundancy, horizontal scaling capabilities, and comprehensive observability integration. The platform is designed to handle high-throughput device communication while maintaining configuration consistency and operational reliability across distributed environments. + +### Recommended Deployment Pattern + +```mermaid +graph TB + subgraph "Load Balancer Layer" + LB[Load Balancer
NGINX/HAProxy] + end + + subgraph "Service Instances" + XA1[XConf Admin
Instance 1] + XA2[XConf Admin
Instance 2] + WC1[XConf WebConfig
Instance 1] + WC2[XConf WebConfig
Instance 2] + UI1[XConf UI
Instance 1] + UI2[XConf UI
Instance 2] + end + + subgraph "Data Layer" + C1[(Cassandra
Node 1)] + C2[(Cassandra
Node 2)] + C3[(Cassandra
Node 3)] + Redis[(Redis Cluster)] + end + + subgraph "External Services" + SAT[SAT Service] + IDP[Identity Provider] + Prometheus[Prometheus] + OTEL[OTEL Collector] + end + + LB --> XA1 + LB --> XA2 + LB --> WC1 + LB --> WC2 + LB --> UI1 + LB --> UI2 + + XA1 --> C1 + XA2 --> C2 + WC1 --> C1 + WC2 --> C3 + + XA1 --> Redis + XA2 --> Redis + WC1 --> Redis + WC2 --> Redis + + XA1 --> SAT + XA2 --> SAT + WC1 --> SAT + WC2 --> SAT +``` + +The deployment architecture implements a layered approach where the load balancer efficiently distributes incoming traffic across multiple service instances based on request type and current system load. Each service type operates multiple instances to ensure high availability and fault tolerance, with automatic failover mechanisms protecting against individual service failures. The Cassandra cluster provides distributed data storage with automatic replication and sharding capabilities, ensuring data consistency and availability even during node failures. Redis cluster integration delivers high-performance caching across all services, significantly reducing database load and improving response times for frequently accessed configuration data. External services integration encompasses authentication systems for secure access control, comprehensive monitoring infrastructure for operational visibility, and distributed tracing capabilities for performance optimization and troubleshooting support. + +### Infrastructure Requirements +- **Compute**: Minimum 2 CPU cores, 4GB RAM per service instance +- **Storage**: SSD storage for database with replication +- **Network**: High-bandwidth connection for firmware distribution +- **Cache**: Redis cluster for high-performance caching +- **Database**: Cassandra cluster with minimum 3 nodes for HA + +### Scaling Considerations +- **Horizontal Scaling**: Stateless services support easy horizontal scaling +- **Database Sharding**: Cassandra provides automatic sharding and replication +- **Cache Strategy**: Multi-level caching with Redis and in-memory caches +- **Load Distribution**: Geographic distribution for global deployments + +## Security Model + +### Authentication Layers +1. **Service-to-Service**: SAT (Security Access Token) based authentication +2. **User Authentication**: Integration with enterprise identity providers +3. **Device Authentication**: MAC address and certificate-based validation +4. **API Security**: JWT tokens with role-based access control + +### Authorization Framework +- **Entity-Based Permissions**: Granular permissions per configuration entity +- **Role-Based Access Control**: Predefined roles with specific capabilities +- **Operation-Level Security**: Read/write permissions per API endpoint +- **Environment Isolation**: Strict separation between environments + +### Security Features +- **Token Validation**: Comprehensive JWT token validation and refresh +- **Request Sanitization**: Input validation and sanitization +- **Audit Logging**: Complete audit trail for all configuration changes +- **Secure Communication**: HTTPS/TLS for all service communications + +## Getting Started + +### Prerequisites +- **Go 1.23+**: For building and running the services +- **Cassandra 3.11+**: For data persistence +- **Redis**: For caching (optional but recommended) +- **Node.js 24.1.0+**: For UI development +- **Git**: For source code management + +### Quick Start + +1. **Clone Repositories**: +```bash +git clone https://github.com/rdkcentral/xconfadmin.git +git clone https://github.com/rdkcentral/xconfui.git +git clone https://github.com/rdkcentral/xconfwebconfig.git +``` + +2. **Start Database**: +```bash +# Start Cassandra and create schema +cassandra -f & +cqlsh -f xconfwebconfig-main/db/db_init.cql +``` + +3. **Configure Services**: +```bash +# Copy and modify configuration files +cp xconfadmin/config/sample_xconfadmin.conf /etc/xconf/xconfadmin.conf +cp xconfwebconfig-main/config/sample_xconfwebconfig.conf /etc/xconf/xconfwebconfig.conf +cp xconfui-main/config/sample_xconfui.conf /etc/xconf/xconfui.conf +``` + +4. **Build and Run Services**: +```bash +# Build XConf Admin +cd xconfadmin && make build +./bin/xconfadmin-linux-amd64 -f /etc/xconf/xconfadmin.conf & + +# Build XConf WebConfig +cd xconfwebconfig-main && make build +./bin/xconfwebconfig-linux-amd64 -f /etc/xconf/xconfwebconfig.conf & + +# Build and Run XConf UI +cd xconfui-main +npm install && grunt install +go run *.go -f /etc/xconf/xconfui.conf & +``` + +5. **Access the System**: +- **Admin UI**: http://localhost:8081 +- **Admin API**: http://localhost:9001/xconfAdminService +- **WebConfig API**: http://localhost:9000/xconf + +### Configuration Tips +- Set environment variables for SAT_CLIENT_ID, SAT_CLIENT_SECRET, and SECURITY_TOKEN_KEY +- Configure appropriate log levels for production deployments +- Enable metrics and tracing for production monitoring +- Use environment-specific configuration files +- Implement proper backup strategies for Cassandra + +### Development Workflow +1. Make changes to source code +2. Run unit tests: `go test ./...` +3. Build and test locally +4. Deploy to staging environment +5. Run integration tests +6. Deploy to production with canary rollout + + +This overview provides a comprehensive understanding of the XConf system architecture, components, and operational patterns. For detailed API documentation, refer to the individual API documentation files in each component directory. diff --git a/docs/tagging_api_documentation.md b/docs/tagging_api_documentation.md new file mode 100644 index 0000000..aee645d --- /dev/null +++ b/docs/tagging_api_documentation.md @@ -0,0 +1,519 @@ +# XConf Tagging API Documentation + +## Overview +The XConf Tagging API provides comprehensive tag management capabilities for RDK device grouping and configuration targeting. It enables dynamic device categorization through tag-based systems, supporting both individual member management and percentage-based distribution for advanced deployment strategies. + +**Base URL**: `/taggingService` + +## Authentication +All endpoints require authentication via JWT token or session-based authentication. Each request is validated for appropriate permissions based on the tagging operations being performed. + +--- + +# Tag Management APIs + +## Get All Tags +Retrieve all available tags in the system: + +**GET** `http://:/taggingService/tags` + +**Query Parameters:** +- `full` (optional): When present, returns complete tag objects with all members. Without this parameter, returns only tag IDs. + +
+Response Body (without full parameter): Array of tag IDs + +```json +[ + "production_devices", + "beta_testers", + "development_units", + "canary_group_1" +] +``` +
+ +
+Response Body (with full parameter): Array of complete tag objects + +```json +[ + { + "id": "production_devices", + "members": [ + "AA:BB:CC:DD:EE:01", + "AA:BB:CC:DD:EE:02", + "AA:BB:CC:DD:EE:03" + ], + "updated": 1699875600000 + }, + { + "id": "beta_testers", + "members": [ + "AA:BB:CC:DD:EE:10", + "AA:BB:CC:DD:EE:11" + ], + "updated": 1699875500000 + } +] +``` +
+ +Response Codes: 200, 500 + +--- + +## Get Tag by ID +Retrieve a specific tag by its identifier: + +**GET** `http://:/taggingService/tags/{tag}` + +**Path Parameters:** +- `tag` (required): Tag identifier + +
+Response Body: Tag object with complete information + +```json +{ + "id": "production_devices", + "members": [ + "AA:BB:CC:DD:EE:01", + "AA:BB:CC:DD:EE:02", + "AA:BB:CC:DD:EE:03", + "AA:BB:CC:DD:EE:04" + ], + "updated": 1699875600000 +} +``` +
+ +Response Codes: 200, 400, 404 + +--- + +## Delete Tag +Delete a specific tag from the system: + +**DELETE** `http://:/taggingService/tags/{tag}` + +**Path Parameters:** +- `tag` (required): Tag identifier to delete + +
+Response Body: No content on successful deletion + +``` +No response body (HTTP 204 No Content) +``` +
+ +Response Codes: 204, 400, 404 + +--- + +## Delete Tag Without Prefix (Development Only) +Delete a tag from XConf without prefix validation - intended for testing and cleanup purposes only: + +**DELETE** `http://:/taggingService/tags/{tag}/noprefix` + +**Path Parameters:** +- `tag` (required): Tag identifier to delete + +**⚠️ Warning**: This endpoint should not be used in production environments as it bypasses standard prefix validation. + +
+Response Body: No content on successful deletion + +``` +No response body (HTTP 204 No Content) +``` +
+ +Response Codes: 204, 400, 404 + +--- + +# Tag Member Management APIs + +## Add Members to Tag +Add multiple members to an existing tag: + +**PUT** `http://:/taggingService/tags/{tag}/members` + +**Path Parameters:** +- `tag` (required): Tag identifier + +**Request Limits:** +- Maximum batch size: 1000 members per request + +
+Request Body: Array of member identifiers + +```json +[ + "AA:BB:CC:DD:EE:05", + "AA:BB:CC:DD:EE:06", + "AA:BB:CC:DD:EE:07", + "device_id_12345" +] +``` +
+ +
+Response Body: Success confirmation + +``` +No response body (HTTP 200 OK) +``` +
+ +Response Codes: 200, 400, 500 + +--- + +## Remove Member from Tag +Remove a single member from a specific tag: + +**DELETE** `http://:/taggingService/tags/{tag}/members/{member}` + +**Path Parameters:** +- `tag` (required): Tag identifier +- `member` (required): Member identifier to remove + +
+Response Body: Updated tag object + +```json +{ + "id": "production_devices", + "members": [ + "AA:BB:CC:DD:EE:01", + "AA:BB:CC:DD:EE:03", + "AA:BB:CC:DD:EE:04" + ], + "updated": 1699875700000 +} +``` +
+ +Response Codes: 204, 400, 404, 500 + +--- + +## Remove Multiple Members from Tag +Remove multiple members from a specific tag in a single operation: + +**DELETE** `http://:/taggingService/tags/{tag}/members` + +**Path Parameters:** +- `tag` (required): Tag identifier + +**Request Limits:** +- Maximum batch size: 1000 members per request + +
+Request Body: Array of member identifiers to remove + +```json +[ + "AA:BB:CC:DD:EE:02", + "AA:BB:CC:DD:EE:05", + "device_id_old_123" +] +``` +
+ +
+Response Body: No content on successful removal + +``` +No response body (HTTP 204 No Content) +``` +
+ +Response Codes: 204, 400, 500 + +--- + +## Get Tag Members +Retrieve all members of a specific tag: + +**GET** `http://:/taggingService/tags/{tag}/members` + +**Path Parameters:** +- `tag` (required): Tag identifier + +
+Response Body: Array of member identifiers + +```json +[ + "AA:BB:CC:DD:EE:01", + "AA:BB:CC:DD:EE:02", + "AA:BB:CC:DD:EE:03", + "AA:BB:CC:DD:EE:04", + "device_id_12345", + "device_id_67890" +] +``` +
+ +Response Codes: 200, 400, 404, 500 + +--- + +## Get Tags by Member +Retrieve all tags that contain a specific member: + +**GET** `http://:/taggingService/tags/members/{member}` + +**Path Parameters:** +- `member` (required): Member identifier to search for + +
+Response Body: Array of tag objects containing the member + +```json +[ + { + "id": "production_devices", + "members": [ + "AA:BB:CC:DD:EE:01", + "AA:BB:CC:DD:EE:02", + "other_device_ids..." + ], + "updated": 1699875600000 + }, + { + "id": "priority_group", + "members": [ + "AA:BB:CC:DD:EE:01", + "priority_device_ids..." + ], + "updated": 1699875550000 + } +] +``` +
+ +Response Codes: 200, 400, 500 + +--- + +# Percentage-Based Distribution APIs + +## Calculate Percentage Value for Member +Calculate the percentage value for a specific member using SipHash algorithm: + +**GET** `http://:/taggingService/tags/members/{member}/percentages/calculation` + +**Path Parameters:** +- `member` (required): Member identifier for percentage calculation + +**Algorithm Details:** +- Uses SipHash with fixed keys for consistent percentage calculation +- Returns deterministic percentage value (0-99) for the given member +- Enables percentage-based rollout strategies + +
+Response Body: Calculated percentage value + +```json +67 +``` +
+ +Response Codes: 200, 400, 500 + +--- + +# Data Models + +## Tag Object +Represents a tag entity with its associated members: + +```json +{ + "id": "string", // Unique tag identifier + "members": ["string"], // Array of member identifiers + "updated": "integer" // Unix timestamp of last update +} +``` + +**Field Descriptions:** +- `id`: Unique identifier for the tag (required) +- `members`: Array of device MAC addresses, device IDs, or other identifiers +- `updated`: Unix timestamp in milliseconds indicating when the tag was last modified + +## Member Identifier Formats +Members can be identified using various formats: + +- **MAC Address**: `AA:BB:CC:DD:EE:FF` +- **Device ID**: `device_12345` +- **Account ID**: `account_67890` +- **Custom Identifier**: Any string-based identifier + +--- + +# Usage Examples + +## Creating a Canary Deployment Tag + +### Step 1: Add devices to a canary tag +```bash +curl -X PUT "http://localhost:9001/taggingService/tags/canary_group_1/members" \ + -H "Content-Type: application/json" \ + -H "Authorization: Bearer YOUR_JWT_TOKEN" \ + -d '[ + "AA:BB:CC:DD:EE:01", + "AA:BB:CC:DD:EE:02", + "AA:BB:CC:DD:EE:03" + ]' +``` + +### Step 2: Verify tag membership +```bash +curl -X GET "http://localhost:9001/taggingService/tags/canary_group_1/members" \ + -H "Authorization: Bearer YOUR_JWT_TOKEN" +``` + +### Step 3: Calculate percentage for device +```bash +curl -X GET "http://localhost:9001/taggingService/tags/members/AA:BB:CC:DD:EE:01/percentages/calculation" \ + -H "Authorization: Bearer YOUR_JWT_TOKEN" +``` + +## Managing Production Device Groups + +### Add multiple devices to production tag +```bash +curl -X PUT "http://localhost:9001/taggingService/tags/production_devices/members" \ + -H "Content-Type: application/json" \ + -H "Authorization: Bearer YOUR_JWT_TOKEN" \ + -d '[ + "device_prod_001", + "device_prod_002", + "device_prod_003" + ]' +``` + +### Remove devices from tag +```bash +curl -X DELETE "http://localhost:9001/taggingService/tags/production_devices/members" \ + -H "Content-Type: application/json" \ + -H "Authorization: Bearer YOUR_JWT_TOKEN" \ + -d '[ + "device_prod_001" + ]' +``` + +### Find all tags for a specific device +```bash +curl -X GET "http://localhost:9001/taggingService/tags/members/device_prod_002" \ + -H "Authorization: Bearer YOUR_JWT_TOKEN" +``` + +--- + +# Error Handling + +## Common Error Responses + +### 400 Bad Request +```json +{ + "status": 400, + "message": "tag is not specified" +} +``` + +### 404 Not Found +```json +{ + "status": 404, + "message": "production_devices tag not found" +} +``` + +### 400 Batch Size Exceeded +```json +{ + "status": 400, + "message": "batch size 1500 exceeds the limit of 1000" +} +``` + +### 400 Empty Member List +```json +{ + "status": 400, + "message": "member list is empty" +} +``` + +## Error Codes Summary + +| Code | Description | Common Causes | +|------|-------------|---------------| +| 200 | Success | Request processed successfully | +| 204 | No Content | Successful deletion or removal | +| 400 | Bad Request | Missing parameters, invalid input, batch size exceeded | +| 401 | Unauthorized | Invalid or missing authentication token | +| 404 | Not Found | Tag or member not found | +| 500 | Internal Server Error | Server processing error | + +--- + +# Best Practices + +## Tag Naming Conventions +- Use descriptive, lowercase names with underscores: `production_devices`, `beta_testers` +- Include environment prefixes: `prod_`, `staging_`, `dev_` +- Use meaningful groupings: `model_specific`, `region_based`, `feature_enabled` + +## Member Management +- **Batch Operations**: Use batch add/remove operations for better performance +- **Validation**: Ensure member identifiers are valid before adding to tags +- **Monitoring**: Track tag membership changes for audit purposes +- **Cleanup**: Regularly remove inactive or decommissioned device members + +## Percentage-Based Rollouts +- **Deterministic Distribution**: Use the percentage calculation API for consistent device assignment +- **Gradual Rollouts**: Start with small percentages and gradually increase +- **Monitoring**: Track rollout progress and device health during percentage-based deployments +- **Rollback Strategy**: Maintain ability to quickly remove devices from percentage-based tags + +## Security Considerations +- **Authentication**: Always use proper JWT tokens for API access +- **Authorization**: Ensure users have appropriate permissions for tag operations +- **Input Validation**: Validate all member identifiers before processing +- **Rate Limiting**: Respect batch size limits to prevent system overload + +--- + +# Integration with XConf Configuration Management + +The Tagging API integrates seamlessly with XConf's configuration management system: + +## Firmware Rules Integration +- Tags can be used as targeting criteria in firmware rules +- Percentage-based rollouts enable gradual firmware deployment +- Tag membership automatically affects device configuration eligibility + +## DCM Configuration Targeting +- Device Control Manager settings can target specific tags +- Log upload policies can be applied to tagged device groups +- Diagnostic data collection can be configured per tag + +## RFC Feature Management +- Feature flags can target devices based on tag membership +- A/B testing scenarios can leverage percentage-based tag distribution +- Feature rollouts can be controlled through dynamic tag membership + +## Telemetry Profile Assignment +- Telemetry collection policies can be assigned to specific tags +- Analytics data can be segmented based on tag-based device groupings +- Performance monitoring can target tagged device populations + +This tagging system provides the foundation for sophisticated device management, enabling precise control over configuration distribution, feature rollouts, and operational policies across diverse RDK device deployments. \ No newline at end of file diff --git a/docs/xconfadmin_API_Documentation.md b/docs/xconfadmin_API_Documentation.md new file mode 100644 index 0000000..9ef4cd5 --- /dev/null +++ b/docs/xconfadmin_API_Documentation.md @@ -0,0 +1,2153 @@ +# XconfAdmin API Documentation + +## Overview +The XconfAdmin API provides comprehensive configuration management for RDK-B devices through a RESTful interface. It manages firmware configurations, device settings, telemetry profiles, feature rules, DCM settings, authentication, and various query operations. + +**Base URL**: `/xconfAdminService` + +## Authentication +Most endpoints require authentication via JWT token or session-based authentication. Each request is validated for appropriate permissions based on the entity type being accessed. + +--- + +# Authentication APIs + +## Get Authentication Provider +Get the available authentication provider configuration: + +**GET** `http://:/provider` + +
+Response Body: Authentication provider information + +```json +{ + "provider": "xerxes", + "loginUrl": "/auth/login", + "enabled": true +} +``` +
+ +Response Codes: 200 + +--- + +## Get Authentication Info +Get current authentication information: + +**GET** `http://:/auth/info` + +
+Response Body: Authentication status + +```json +{ + "authenticated": true, + "username": "admin", + "permissions": ["READ", "WRITE"], + "roles": ["ADMIN"] +} +``` +
+ +Response Codes: 200, 401 + +--- + +## Basic Authentication +Perform basic authentication with username and password: + +**POST** `http://:/auth/basic` + +
+Request Body: Basic authentication credentials + +```json +{ + "username": "admin", + "password": "password123" +} +``` +
+ +
+Response Body: Authentication result + +```json +{ + "success": true, + "token": "jwt-token-here", + "expires": "2025-11-06T10:00:00Z" +} +``` +
+ +Response Codes: 200, 401 + +--- + +# Query APIs + +## Get All Environments +Get all available environments: + +**GET** `http://:/queries/environments` + +
+Response Body: Array of environment objects + +```json +[ + { + "id": "env-001", + "name": "Production", + "description": "Production environment" + }, + { + "id": "env-002", + "name": "Staging", + "description": "Staging environment" + } +] +``` +
+ +Response Codes: 200, 401 + +--- + +## Get Environment by ID +Get specific environment by identifier: + +**GET** `http://:/queries/environments/{id}` + +
+Response Body: Single environment object + +```json +{ + "id": "env-001", + "name": "Production", + "description": "Production environment" +} +``` +
+ +Response Codes: 200, 404, 401 + +--- + +## Get All Models +Get all device models: + +**GET** `http://:/queries/models` + +
+Response Body: Array of model objects + +```json +[ + { + "id": "model-001", + "name": "STB_MODEL_X", + "description": "Set-top box model X" + } +] +``` +
+ +Response Codes: 200, 401 + +--- + +## Get Model by ID +Get specific model by identifier: + +**GET** `http://:/queries/models/{id}` + +
+Response Body: Single model object + +```json +{ + "id": "model-001", + "name": "STB_MODEL_X", + "description": "Set-top box model X" +} +``` +
+ +Response Codes: 200, 404, 401 + +--- + +## Get IP Address Groups +Get all IP address groups: + +**GET** `http://:/queries/ipAddressGroups` + +
+Response Body: Array of IP address group objects + +```json +[ + { + "id": "ip-group-001", + "name": "Production IPs", + "ipAddresses": ["192.168.1.100", "192.168.1.101"] + } +] +``` +
+ +Response Codes: 200, 401 + +--- + +## Get IP Address Group by IP +Get IP address groups containing specific IP: + +**GET** `http://:/queries/ipAddressGroups/byIp/{ipAddress}` + +
+Response Body: Array of matching IP address groups + +```json +[ + { + "id": "ip-group-001", + "name": "Production IPs", + "ipAddresses": ["192.168.1.100", "192.168.1.101"] + } +] +``` +
+ +Response Codes: 200, 404, 401 + +--- + +## Get Firmware Configurations +Get all firmware configurations: + +**GET** `http://:/queries/firmwares` + +
+Response Body: Array of firmware configuration objects + +```json +[ + { + "id": "fw-001", + "firmwareFilename": "firmware_v1.0.bin", + "version": "1.0.0", + "description": "Production firmware v1.0", + "supportedModelIds": ["model-001"], + "firmwareDownloadProtocol": "http", + "firmwareLocation": "http://cdn.example.com/firmware/" + } +] +``` +
+ +Response Codes: 200, 401 + +--- + +## Get Firmware Configuration by ID +Get specific firmware configuration by ID: + +**GET** `http://:/queries/firmwares/{id}` + +
+Response Body: Single firmware configuration object + +```json +{ + "id": "fw-001", + "firmwareFilename": "firmware_v1.0.bin", + "version": "1.0.0", + "description": "Production firmware v1.0", + "supportedModelIds": ["model-001"], + "firmwareDownloadProtocol": "http", + "firmwareLocation": "http://cdn.example.com/firmware/" +} +``` +
+ +Response Codes: 200, 404, 401 + +--- + +# Model Management APIs + +## Get All Models +Get all device models with pagination support: + +**GET** `http://:/model` + +
+Response Body: Array of model objects + +```json +[ + { + "id": "model-001", + "name": "STB_MODEL_X", + "description": "Set-top box model X" + } +] +``` +
+ +Response Codes: 200, 401 + +--- + +## Create Model +Create a new device model: + +**POST** `http://:/model` + +
+Request Body: Model creation data + +```json +{ + "id": "model-002", + "name": "STB_MODEL_Y", + "description": "Set-top box model Y" +} +``` +
+ +
+Response Body: Created model object + +```json +{ + "id": "model-002", + "name": "STB_MODEL_Y", + "description": "Set-top box model Y" +} +``` +
+ +Response Codes: 201, 400, 401 + +--- + +## Update Model +Update an existing device model: + +**PUT** `http://:/model` + +
+Request Body: Model update data + +```json +{ + "id": "model-002", + "name": "STB_MODEL_Y_Updated", + "description": "Updated set-top box model Y" +} +``` +
+ +
+Response Body: Updated model object + +```json +{ + "id": "model-002", + "name": "STB_MODEL_Y_Updated", + "description": "Updated set-top box model Y" +} +``` +
+ +Response Codes: 200, 400, 404, 401 + +--- + +## Delete Model +Delete a device model by ID: + +**DELETE** `http://:/model/{id}` + +Response Codes: 204, 404, 401 + +--- + +# Environment Management APIs + +## Get All Environments +Get all environments with pagination support: + +**GET** `http://:/environment` + +
+Response Body: Array of environment objects + +```json +[ + { + "id": "env-001", + "name": "Production", + "description": "Production environment" + } +] +``` +
+ +Response Codes: 200, 401 + +--- + +## Create Environment +Create a new environment: + +**POST** `http://:/environment` + +
+Request Body: Environment creation data + +```json +{ + "id": "env-003", + "name": "Development", + "description": "Development environment" +} +``` +
+ +
+Response Body: Created environment object + +```json +{ + "id": "env-003", + "name": "Development", + "description": "Development environment" +} +``` +
+ +Response Codes: 201, 400, 401 + +--- + +## Update Environment +Update an existing environment: + +**PUT** `http://:/environment` + +
+Request Body: Environment update data + +```json +{ + "id": "env-003", + "name": "Development_Updated", + "description": "Updated development environment" +} +``` +
+ +
+Response Body: Updated environment object + +```json +{ + "id": "env-003", + "name": "Development_Updated", + "description": "Updated development environment" +} +``` +
+ +Response Codes: 200, 400, 404, 401 + +--- + +## Delete Environment +Delete an environment by ID: + +**DELETE** `http://:/environment/{id}` + +Response Codes: 204, 404, 401 + +--- + +# Firmware Rule Management APIs + +## Get All Firmware Rules +Get all firmware rules with filtering: + +**GET** `http://:/firmwarerule/filtered?pageNumber=1&pageSize=10` + +
+Response Body: Array of firmware rule objects + +```json +[ + { + "id": "fw-rule-001", + "name": "Production STB Rule", + "type": "MAC_RULE", + "rule": { + "condition": { + "freeArg": "model", + "operation": "IS", + "fixedArg": "STB_MODEL_X" + } + }, + "applicableAction": { + "actionType": "RULE", + "configId": "fw-001" + }, + "applicationType": "stb" + } +] +``` +
+ +Response Codes: 200, 401 + +--- + +## Get Firmware Rule by ID +Get specific firmware rule by ID: + +**GET** `http://:/firmwarerule/{id}` + +
+Response Body: Single firmware rule object + +```json +{ + "id": "fw-rule-001", + "name": "Production STB Rule", + "type": "MAC_RULE", + "rule": { + "condition": { + "freeArg": "model", + "operation": "IS", + "fixedArg": "STB_MODEL_X" + } + }, + "applicableAction": { + "actionType": "RULE", + "configId": "fw-001" + }, + "applicationType": "stb" +} +``` +
+ +Response Codes: 200, 404, 401 + +--- + +## Create Firmware Rule +Create a new firmware rule: + +**POST** `http://:/firmwarerule` + +
+Request Body: Firmware rule creation data + +```json +{ + "name": "New STB Rule", + "type": "MAC_RULE", + "rule": { + "condition": { + "freeArg": "model", + "operation": "IS", + "fixedArg": "STB_MODEL_Y" + } + }, + "applicableAction": { + "actionType": "RULE", + "configId": "fw-002" + }, + "applicationType": "stb" +} +``` +
+ +
+Response Body: Created firmware rule object + +```json +{ + "id": "fw-rule-002", + "name": "New STB Rule", + "type": "MAC_RULE", + "rule": { + "condition": { + "freeArg": "model", + "operation": "IS", + "fixedArg": "STB_MODEL_Y" + } + }, + "applicableAction": { + "actionType": "RULE", + "configId": "fw-002" + }, + "applicationType": "stb" +} +``` +
+ +Response Codes: 201, 400, 401 + +--- + +## Update Firmware Rule +Update an existing firmware rule: + +**PUT** `http://:/firmwarerule` + +
+Request Body: Firmware rule update data + +```json +{ + "id": "fw-rule-002", + "name": "Updated STB Rule", + "type": "MAC_RULE", + "rule": { + "condition": { + "freeArg": "model", + "operation": "IS", + "fixedArg": "STB_MODEL_Y" + } + }, + "applicableAction": { + "actionType": "RULE", + "configId": "fw-002" + }, + "applicationType": "stb" +} +``` +
+ +
+Response Body: Updated firmware rule object + +```json +{ + "id": "fw-rule-002", + "name": "Updated STB Rule", + "type": "MAC_RULE", + "rule": { + "condition": { + "freeArg": "model", + "operation": "IS", + "fixedArg": "STB_MODEL_Y" + } + }, + "applicableAction": { + "actionType": "RULE", + "configId": "fw-002" + }, + "applicationType": "stb" +} +``` +
+ +Response Codes: 200, 400, 404, 401 + +--- + +## Delete Firmware Rule +Delete a firmware rule by ID: + +**DELETE** `http://:/firmwarerule/{id}` + +Response Codes: 204, 404, 401 + +--- + +# Firmware Configuration APIs + +## Get All Firmware Configurations +Get all firmware configurations: + +**GET** `http://:/firmwareconfig` + +
+Response Body: Array of firmware configuration objects + +```json +[ + { + "id": "fw-001", + "firmwareFilename": "firmware_v1.0.bin", + "version": "1.0.0", + "description": "Production firmware v1.0", + "supportedModelIds": ["model-001"], + "firmwareDownloadProtocol": "http", + "firmwareLocation": "http://cdn.example.com/firmware/" + } +] +``` +
+ +Response Codes: 200, 401 + +--- + +## Create Firmware Configuration +Create a new firmware configuration: + +**POST** `http://:/firmwareconfig` + +
+Request Body: Firmware configuration creation data + +```json +{ + "firmwareFilename": "firmware_v2.0.bin", + "version": "2.0.0", + "description": "New firmware v2.0", + "supportedModelIds": ["model-001", "model-002"], + "firmwareDownloadProtocol": "https", + "firmwareLocation": "https://secure-cdn.example.com/firmware/" +} +``` +
+ +
+Response Body: Created firmware configuration object + +```json +{ + "id": "fw-002", + "firmwareFilename": "firmware_v2.0.bin", + "version": "2.0.0", + "description": "New firmware v2.0", + "supportedModelIds": ["model-001", "model-002"], + "firmwareDownloadProtocol": "https", + "firmwareLocation": "https://secure-cdn.example.com/firmware/" +} +``` +
+ +Response Codes: 201, 400, 401 + +--- + +## Update Firmware Configuration +Update an existing firmware configuration: + +**PUT** `http://:/firmwareconfig` + +
+Request Body: Firmware configuration update data + +```json +{ + "id": "fw-002", + "firmwareFilename": "firmware_v2.1.bin", + "version": "2.1.0", + "description": "Updated firmware v2.1", + "supportedModelIds": ["model-001", "model-002"], + "firmwareDownloadProtocol": "https", + "firmwareLocation": "https://secure-cdn.example.com/firmware/" +} +``` +
+ +
+Response Body: Updated firmware configuration object + +```json +{ + "id": "fw-002", + "firmwareFilename": "firmware_v2.1.bin", + "version": "2.1.0", + "description": "Updated firmware v2.1", + "supportedModelIds": ["model-001", "model-002"], + "firmwareDownloadProtocol": "https", + "firmwareLocation": "https://secure-cdn.example.com/firmware/" +} +``` +
+ +Response Codes: 200, 400, 404, 401 + +--- + +## Delete Firmware Configuration +Delete a firmware configuration by ID: + +**DELETE** `http://:/firmwareconfig/{id}` + +Response Codes: 204, 404, 401 + +--- + +# DCM (Device Configuration Management) APIs + +## Get All DCM Formulas +Get all DCM formulas for authenticated application type: + +**GET** `http://:/dcm/formula?applicationType=stb` + +
+Response Body: Array of DCM Formula objects + +```json +[ + { + "id": "formula-001", + "name": "STB Configuration Rule", + "description": "Configuration for STB devices", + "priority": 1, + "ruleExpression": "model == 'STB_MODEL_X'", + "percentage": 100, + "percentageL1": 50.0, + "percentageL2": 30.0, + "percentageL3": 20.0, + "applicationType": "stb", + "rule": { + "condition": { + "freeArg": "model", + "operation": "IS", + "fixedArg": "STB_MODEL_X" + } + } + } +] +``` +
+ +Response Codes: 200, 401 + +--- + +## Create DCM Formula +Create a new DCM formula: + +**POST** `http://:/dcm/formula?applicationType=stb` + +
+Request Body: DCM Formula creation data + +```json +{ + "name": "New STB Configuration Rule", + "description": "New configuration for STB devices", + "priority": 2, + "ruleExpression": "model == 'STB_MODEL_Y'", + "percentage": 75, + "percentageL1": 40.0, + "percentageL2": 35.0, + "percentageL3": 25.0, + "applicationType": "stb", + "rule": { + "condition": { + "freeArg": "model", + "operation": "IS", + "fixedArg": "STB_MODEL_Y" + } + } +} +``` +
+ +
+Response Body: Created DCM Formula object + +```json +{ + "id": "formula-002", + "name": "New STB Configuration Rule", + "description": "New configuration for STB devices", + "priority": 2, + "ruleExpression": "model == 'STB_MODEL_Y'", + "percentage": 75, + "percentageL1": 40.0, + "percentageL2": 35.0, + "percentageL3": 25.0, + "applicationType": "stb", + "rule": { + "condition": { + "freeArg": "model", + "operation": "IS", + "fixedArg": "STB_MODEL_Y" + } + } +} +``` +
+ +Response Codes: 201, 400, 401 + +--- + +## Get All Device Settings +Get all device settings: + +**GET** `http://:/dcm/deviceSettings` + +
+Response Body: Array of Device Settings objects + +```json +[ + { + "id": "device-settings-001", + "name": "STB Device Settings", + "checkOnReboot": true, + "settingsAreActive": true, + "schedule": { + "type": "CronExpression", + "expression": "0 2 * * *", + "timeWindowMinutes": 60, + "startDate": "2025-01-01", + "endDate": "2025-12-31" + }, + "configData": { + "logLevel": "INFO", + "uploadOnReboot": true + } + } +] +``` +
+ +Response Codes: 200, 401 + +--- + +## Get All Log Upload Settings +Get all log upload settings: + +**GET** `http://:/dcm/logUploadSettings` + +
+Response Body: Array of Log Upload Settings objects + +```json +[ + { + "id": "log-upload-001", + "name": "Production Log Upload", + "uploadOnReboot": true, + "numberOfDays": 7, + "areSettingsActive": true, + "modeToGetLogFiles": "LogFiles", + "schedule": { + "type": "CronExpression", + "expression": "0 3 * * *", + "timeWindowMinutes": 120 + }, + "logFiles": [ + { + "name": "system.log", + "logFileName": "/var/log/system.log" + } + ], + "logUploadSettings": { + "uploadRepositoryName": "prod-repo", + "uploadProtocol": "HTTPS" + } + } +] +``` +
+ +Response Codes: 200, 401 + +--- + +## Get All VOD Settings +Get all Video On Demand settings: + +**GET** `http://:/dcm/vodsettings` + +
+Response Body: Array of VOD Settings objects + +```json +[ + { + "id": "vod-settings-001", + "name": "Production VOD Settings", + "locationsURL": "https://vod.example.com/locations", + "srmIPList": ["192.168.1.10", "192.168.1.11"], + "ipNames": ["SRM-1", "SRM-2"], + "ipList": ["192.168.1.10", "192.168.1.11"] + } +] +``` +
+ +Response Codes: 200, 401 + +--- + +## Get All Upload Repositories +Get all upload repository settings: + +**GET** `http://:/dcm/uploadRepository` + +
+Response Body: Array of Upload Repository objects + +```json +[ + { + "id": "repo-001", + "name": "Production Repository", + "description": "Production log upload repository", + "url": "https://logs.example.com/upload", + "protocol": "HTTPS", + "applicationType": "stb" + } +] +``` +
+ +Response Codes: 200, 401 + +--- + +# RFC (Remote Feature Control) APIs + +## Get All Features +Get all feature definitions: + +**GET** `http://:/rfc/feature` + +
+Response Body: Array of Feature objects + +```json +[ + { + "id": "feature-001", + "featureName": "WiFiDualBand", + "effectiveImmediate": true, + "enable": true, + "configData": { + "band2g": "enabled", + "band5g": "enabled" + }, + "applicationType": "stb" + } +] +``` +
+ +Response Codes: 200, 401 + +--- + +## Create Feature +Create a new feature: + +**POST** `http://:/rfc/feature` + +
+Request Body: Feature creation data + +```json +{ + "featureName": "NewFeature", + "effectiveImmediate": false, + "enable": true, + "configData": { + "setting1": "value1", + "setting2": "value2" + }, + "applicationType": "stb" +} +``` +
+ +
+Response Body: Created Feature object + +```json +{ + "id": "feature-002", + "featureName": "NewFeature", + "effectiveImmediate": false, + "enable": true, + "configData": { + "setting1": "value1", + "setting2": "value2" + }, + "applicationType": "stb" +} +``` +
+ +Response Codes: 201, 400, 401 + +--- + +## Get All Feature Rules +Get all feature rules: + +**GET** `http://:/rfc/featurerule` + +
+Response Body: Array of Feature Rule objects + +```json +[ + { + "id": "feature-rule-001", + "name": "WiFi Feature Rule", + "rule": { + "condition": { + "freeArg": "model", + "operation": "IS", + "fixedArg": "STB_MODEL_X" + } + }, + "priority": 1, + "featureIds": ["feature-001"], + "applicationType": "stb" + } +] +``` +
+ +Response Codes: 200, 401 + +--- + +## Create Feature Rule +Create a new feature rule: + +**POST** `http://:/rfc/featurerule` + +
+Request Body: Feature Rule creation data + +```json +{ + "name": "New Feature Rule", + "rule": { + "condition": { + "freeArg": "model", + "operation": "IS", + "fixedArg": "STB_MODEL_Y" + } + }, + "priority": 2, + "featureIds": ["feature-002"], + "applicationType": "stb" +} +``` +
+ +
+Response Body: Created Feature Rule object + +```json +{ + "id": "feature-rule-002", + "name": "New Feature Rule", + "rule": { + "condition": { + "freeArg": "model", + "operation": "IS", + "fixedArg": "STB_MODEL_Y" + } + }, + "priority": 2, + "featureIds": ["feature-002"], + "applicationType": "stb" +} +``` +
+ +Response Codes: 201, 400, 401 + +--- + +# Telemetry APIs + +## Get All Telemetry Profiles (v1) +Get all telemetry v1 profiles: + +**GET** `http://:/telemetry/profile` + +
+Response Body: Array of Telemetry Profile objects + +```json +[ + { + "id": "telemetry-profile-001", + "name": "STB Telemetry Profile", + "schedule": "0 */15 * * * *", + "expires": 0, + "telemetryProfile": [ + { + "header": "System_Info", + "content": "Device.DeviceInfo.Manufacturer,Device.DeviceInfo.ModelName", + "type": "JSON", + "pollingFrequency": "900" + } + ], + "applicationType": "stb" + } +] +``` +
+ +Response Codes: 200, 401 + +--- + +## Create Telemetry Profile (v1) +Create a new telemetry v1 profile: + +**POST** `http://:/telemetry/profile` + +
+Request Body: Telemetry Profile creation data + +```json +{ + "name": "New STB Telemetry Profile", + "schedule": "0 */30 * * * *", + "expires": 0, + "telemetryProfile": [ + { + "header": "Memory_Info", + "content": "Device.DeviceInfo.MemoryStatus.Total,Device.DeviceInfo.MemoryStatus.Free", + "type": "JSON", + "pollingFrequency": "1800" + } + ], + "applicationType": "stb" +} +``` +
+ +
+Response Body: Created Telemetry Profile object + +```json +{ + "id": "telemetry-profile-002", + "name": "New STB Telemetry Profile", + "schedule": "0 */30 * * * *", + "expires": 0, + "telemetryProfile": [ + { + "header": "Memory_Info", + "content": "Device.DeviceInfo.MemoryStatus.Total,Device.DeviceInfo.MemoryStatus.Free", + "type": "JSON", + "pollingFrequency": "1800" + } + ], + "applicationType": "stb" +} +``` +
+ +Response Codes: 201, 400, 401 + +--- + +## Get All Telemetry Profiles (v2) +Get all telemetry v2 profiles: + +**GET** `http://:/telemetry/v2/profile` + +
+Response Body: Array of Telemetry v2 Profile objects + +```json +[ + { + "id": "telemetry-v2-profile-001", + "name": "STB Telemetry v2 Profile", + "protocol": "HTTP", + "encodingType": "JSON", + "reportingInterval": 900, + "timeReference": "0001-01-01T00:00:00Z", + "parameter": [ + { + "name": "Device.WiFi.Radio.1.Stats.BytesSent", + "reference": "0001-01-01T00:00:00Z", + "use": "Absolute" + } + ], + "applicationType": "stb" + } +] +``` +
+ +Response Codes: 200, 401 + +--- + +## Create Telemetry Profile (v2) +Create a new telemetry v2 profile: + +**POST** `http://:/telemetry/v2/profile` + +
+Request Body: Telemetry v2 Profile creation data + +```json +{ + "name": "New STB Telemetry v2 Profile", + "protocol": "HTTPS", + "encodingType": "JSON", + "reportingInterval": 1800, + "timeReference": "0001-01-01T00:00:00Z", + "parameter": [ + { + "name": "Device.WiFi.Radio.2.Stats.BytesSent", + "reference": "0001-01-01T00:00:00Z", + "use": "Absolute" + } + ], + "applicationType": "stb" +} +``` +
+ +
+Response Body: Created Telemetry v2 Profile object + +```json +{ + "id": "telemetry-v2-profile-002", + "name": "New STB Telemetry v2 Profile", + "protocol": "HTTPS", + "encodingType": "JSON", + "reportingInterval": 1800, + "timeReference": "0001-01-01T00:00:00Z", + "parameter": [ + { + "name": "Device.WiFi.Radio.2.Stats.BytesSent", + "reference": "0001-01-01T00:00:00Z", + "use": "Absolute" + } + ], + "applicationType": "stb" +} +``` +
+ +Response Codes: 201, 400, 401 + +--- + +# Settings APIs + +## Get All Setting Profiles +Get all setting profiles: + +**GET** `http://:/setting/profile` + +
+Response Body: Array of Setting Profile objects + +```json +[ + { + "id": "setting-profile-001", + "settingProfileId": "wifi-settings", + "settingType": "EPON", + "properties": { + "wifiEnabled": "true", + "channel": "auto" + }, + "applicationType": "stb" + } +] +``` +
+ +Response Codes: 200, 401 + +--- + +## Create Setting Profile +Create a new setting profile: + +**POST** `http://:/setting/profile` + +
+Request Body: Setting Profile creation data + +```json +{ + "settingProfileId": "network-settings", + "settingType": "EPON", + "properties": { + "dhcpEnabled": "true", + "dnsServer": "8.8.8.8" + }, + "applicationType": "stb" +} +``` +
+ +
+Response Body: Created Setting Profile object + +```json +{ + "id": "setting-profile-002", + "settingProfileId": "network-settings", + "settingType": "EPON", + "properties": { + "dhcpEnabled": "true", + "dnsServer": "8.8.8.8" + }, + "applicationType": "stb" +} +``` +
+ +Response Codes: 201, 400, 401 + +--- + +## Get All Setting Rules +Get all setting rules: + +**GET** `http://:/setting/rule` + +
+Response Body: Array of Setting Rule objects + +```json +[ + { + "id": "setting-rule-001", + "name": "WiFi Setting Rule", + "rule": { + "condition": { + "freeArg": "model", + "operation": "IS", + "fixedArg": "STB_MODEL_X" + } + }, + "boundSettingId": "setting-profile-001", + "applicationType": "stb" + } +] +``` +
+ +Response Codes: 200, 401 + +--- + +## Create Setting Rule +Create a new setting rule: + +**POST** `http://:/setting/rule` + +
+Request Body: Setting Rule creation data + +```json +{ + "name": "Network Setting Rule", + "rule": { + "condition": { + "freeArg": "model", + "operation": "IS", + "fixedArg": "STB_MODEL_Y" + } + }, + "boundSettingId": "setting-profile-002", + "applicationType": "stb" +} +``` +
+ +
+Response Body: Created Setting Rule object + +```json +{ + "id": "setting-rule-002", + "name": "Network Setting Rule", + "rule": { + "condition": { + "freeArg": "model", + "operation": "IS", + "fixedArg": "STB_MODEL_Y" + } + }, + "boundSettingId": "setting-profile-002", + "applicationType": "stb" +} +``` +
+ +Response Codes: 201, 400, 401 + +--- + +# Percentage Filter APIs + +## Get All Percentage Beans +Get all percentage filter beans: + +**GET** `http://:/percentfilter/percentageBean` + +
+Response Body: Array of Percentage Bean objects + +```json +[ + { + "id": "percent-bean-001", + "name": "Production Rollout", + "active": true, + "value": 25.0, + "firmwareCheckRequired": true, + "rebootDecoupled": false, + "applicationType": "stb", + "lastKnownGood": "fw-001", + "intermediateVersion": "fw-002", + "firmwareVersions": ["fw-001", "fw-002"], + "distributions": [ + { + "configId": "fw-002", + "percentage": 25.0 + } + ] + } +] +``` +
+ +Response Codes: 200, 401 + +--- + +## Create Percentage Bean +Create a new percentage filter bean: + +**POST** `http://:/percentfilter/percentageBean` + +
+Request Body: Percentage Bean creation data + +```json +{ + "name": "Beta Rollout", + "active": true, + "value": 10.0, + "firmwareCheckRequired": true, + "rebootDecoupled": false, + "applicationType": "stb", + "lastKnownGood": "fw-001", + "intermediateVersion": "fw-003", + "firmwareVersions": ["fw-001", "fw-003"], + "distributions": [ + { + "configId": "fw-003", + "percentage": 10.0 + } + ] +} +``` +
+ +
+Response Body: Created Percentage Bean object + +```json +{ + "id": "percent-bean-002", + "name": "Beta Rollout", + "active": true, + "value": 10.0, + "firmwareCheckRequired": true, + "rebootDecoupled": false, + "applicationType": "stb", + "lastKnownGood": "fw-001", + "intermediateVersion": "fw-003", + "firmwareVersions": ["fw-001", "fw-003"], + "distributions": [ + { + "configId": "fw-003", + "percentage": 10.0 + } + ] +} +``` +
+ +Response Codes: 201, 400, 401 + +--- + +# Namespaced List APIs + +## Get All Namespaced Lists +Get all generic namespaced lists: + +**GET** `http://:/genericnamespacedlist` + +
+Response Body: Array of Namespaced List objects + +```json +[ + { + "id": "ns-list-001", + "typeName": "MAC_LIST", + "data": ["00:11:22:33:44:55", "AA:BB:CC:DD:EE:FF"], + "applicationType": "stb" + } +] +``` +
+ +Response Codes: 200, 401 + +--- + +## Create Namespaced List +Create a new generic namespaced list: + +**POST** `http://:/genericnamespacedlist` + +
+Request Body: Namespaced List creation data + +```json +{ + "id": "ns-list-002", + "typeName": "IP_LIST", + "data": ["192.168.1.100", "192.168.1.101"], + "applicationType": "stb" +} +``` +
+ +
+Response Body: Created Namespaced List object + +```json +{ + "id": "ns-list-002", + "typeName": "IP_LIST", + "data": ["192.168.1.100", "192.168.1.101"], + "applicationType": "stb" +} +``` +
+ +Response Codes: 201, 400, 401 + +--- + +# Test Page APIs + +## Firmware Test Page +Test firmware rule evaluation: + +**POST** `http://:/firmwarerule/testpage` + +
+Request Body: Test parameters + +```json +{ + "parameters": { + "mac": "00:11:22:33:44:55", + "model": "STB_MODEL_X", + "env": "PROD" + }, + "applicationType": "stb" +} +``` +
+ +
+Response Body: Test result + +```json +{ + "result": "RULE_MATCH", + "firmwareConfig": { + "id": "fw-001", + "firmwareFilename": "firmware_v1.0.bin", + "version": "1.0.0" + }, + "explanation": "Device matches firmware rule fw-rule-001" +} +``` +
+ +Response Codes: 200, 400, 401 + +--- + +## DCM Test Page +Test DCM rule evaluation: + +**POST** `http://:/dcm/testpage` + +
+Request Body: Test parameters + +```json +{ + "parameters": { + "mac": "00:11:22:33:44:55", + "model": "STB_MODEL_X", + "env": "PROD" + }, + "applicationType": "stb" +} +``` +
+ +
+Response Body: DCM test result + +```json +{ + "result": "FORMULA_MATCH", + "dcmSettings": { + "logUploadSettings": { + "name": "Production Log Upload", + "uploadOnReboot": true + } + }, + "explanation": "Device matches DCM formula formula-001" +} +``` +
+ +Response Codes: 200, 400, 401 + +--- + +## Settings Test Page +Test setting rule evaluation: + +**POST** `http://:/settings/testpage` + +
+Request Body: Test parameters + +```json +{ + "parameters": { + "mac": "00:11:22:33:44:55", + "model": "STB_MODEL_X", + "env": "PROD" + }, + "applicationType": "stb" +} +``` +
+ +
+Response Body: Settings test result + +```json +{ + "result": "RULE_MATCH", + "settingsProfile": { + "id": "setting-profile-001", + "settingProfileId": "wifi-settings", + "properties": { + "wifiEnabled": "true" + } + }, + "explanation": "Device matches setting rule setting-rule-001" +} +``` +
+ +Response Codes: 200, 400, 401 + +--- + +## RFC Test Page +Test RFC feature rule evaluation: + +**POST** `http://:/rfc/test` + +
+Request Body: Test parameters + +```json +{ + "parameters": { + "mac": "00:11:22:33:44:55", + "model": "STB_MODEL_X", + "env": "PROD" + }, + "applicationType": "stb" +} +``` +
+ +
+Response Body: RFC test result + +```json +{ + "result": "RULE_MATCH", + "features": [ + { + "id": "feature-001", + "featureName": "WiFiDualBand", + "enable": true, + "configData": { + "band2g": "enabled", + "band5g": "enabled" + } + } + ], + "explanation": "Device matches feature rule feature-rule-001" +} +``` +
+ +Response Codes: 200, 400, 401 + +--- + +# System Information APIs + +## Get System Statistics +Get system statistics and information: + +**GET** `http://:/stats` + +
+Response Body: System statistics + +```json +{ + "totalFirmwareRules": 150, + "totalFirmwareConfigs": 75, + "totalFeatures": 25, + "totalFeatureRules": 50, + "totalDcmFormulas": 10, + "totalDeviceSettings": 5, + "cacheStatus": "ACTIVE", + "lastRefreshTime": "2025-11-05T10:00:00Z" +} +``` +
+ +Response Codes: 200, 401 + +--- + +## Refresh All Caches +Refresh all system caches: + +**GET** `http://:/info/refreshAll` + +
+Response Body: Cache refresh result + +```json +{ + "status": "SUCCESS", + "message": "All caches refreshed successfully", + "refreshedTables": ["firmwareconfig", "firmwarerule", "feature", "featurerule", "dcmrule"], + "timestamp": "2025-11-05T10:05:00Z" +} +``` +
+ +Response Codes: 200, 401 + +--- + +## Get Table Information +Get information about specific database table: + +**GET** `http://:/info/tables/{tableName}` + +
+Response Body: Table information + +```json +{ + "tableName": "firmwareconfig", + "rowCount": 75, + "lastModified": "2025-11-05T09:30:00Z", + "cacheStatus": "LOADED", + "sizeBytes": 524288 +} +``` +
+ +Response Codes: 200, 404, 401 + +--- + +# Change Management APIs + +## Get All Changes +Get all pending changes: + +**GET** `http://:/change/all` + +
+Response Body: Array of change objects + +```json +[ + { + "id": "change-001", + "entityType": "TELEMETRY_PROFILE", + "entityId": "telemetry-profile-001", + "operation": "UPDATE", + "oldEntity": {...}, + "newEntity": {...}, + "author": "admin", + "created": "2025-11-05T09:00:00Z" + } +] +``` +
+ +Response Codes: 200, 401 + +--- + +## Approve Change +Approve a pending change: + +**GET** `http://:/change/approve/{changeId}` + +
+Response Body: Approval result + +```json +{ + "approved": true, + "changeId": "change-001", + "approvedBy": "admin", + "approvedAt": "2025-11-05T10:00:00Z" +} +``` +
+ +Response Codes: 200, 404, 401 + +--- + +## Cancel Change +Cancel a pending change: + +**GET** `http://:/change/cancel/{changeId}` + +
+Response Body: Cancellation result + +```json +{ + "cancelled": true, + "changeId": "change-001", + "cancelledBy": "admin", + "cancelledAt": "2025-11-05T10:00:00Z" +} +``` +
+ +Response Codes: 200, 404, 401 + +--- + +# Application Settings APIs + +## Get Application Settings +Get current application settings: + +**GET** `http://:/appsettings` + +
+Response Body: Application settings object + +```json +{ + "applicationName": "XconfAdmin", + "version": "1.0.0", + "maxFirmwareRuleSize": 1000, + "enableChangeApproval": true, + "defaultApplicationType": "stb", + "supportedApplicationTypes": ["stb", "rdkv"] +} +``` +
+ +Response Codes: 200, 401 + +--- + +## Update Application Settings +Update application settings: + +**PUT** `http://:/appsettings` + +
+Request Body: Application settings update data + +```json +{ + "applicationName": "XconfAdmin", + "version": "1.1.0", + "maxFirmwareRuleSize": 1200, + "enableChangeApproval": true, + "defaultApplicationType": "stb", + "supportedApplicationTypes": ["stb", "rdkv", "rdkc"] +} +``` +
+ +
+Response Body: Updated application settings + +```json +{ + "applicationName": "XconfAdmin", + "version": "1.1.0", + "maxFirmwareRuleSize": 1200, + "enableChangeApproval": true, + "defaultApplicationType": "stb", + "supportedApplicationTypes": ["stb", "rdkv", "rdkc"] +} +``` +
+ +Response Codes: 200, 400, 401 + +--- + +# Error Handling + +## Common Error Responses + +### 400 Bad Request +```json +{ + "status": 400, + "error": "Bad Request", + "message": "Invalid request parameters", + "timestamp": "2025-11-05T10:00:00Z" +} +``` + +### 401 Unauthorized +```json +{ + "status": 401, + "error": "Unauthorized", + "message": "Authentication required", + "timestamp": "2025-11-05T10:00:00Z" +} +``` + +### 403 Forbidden +```json +{ + "status": 403, + "error": "Forbidden", + "message": "Insufficient permissions", + "timestamp": "2025-11-05T10:00:00Z" +} +``` + +### 404 Not Found +```json +{ + "status": 404, + "error": "Not Found", + "message": "Resource not found", + "timestamp": "2025-11-05T10:00:00Z" +} +``` + +### 500 Internal Server Error +```json +{ + "status": 500, + "error": "Internal Server Error", + "message": "An unexpected error occurred", + "timestamp": "2025-11-05T10:00:00Z" +} +``` + +--- + +# Request/Response Headers + +## Common Request Headers +- `Content-Type: application/json` +- `Accept: application/json` +- `Authorization: Bearer ` (for authenticated endpoints) + +## Common Response Headers +- `Content-Type: application/json` +- `Cache-Control: no-cache` +- `X-Request-ID: ` + +--- + +# Rate Limiting +All endpoints are subject to rate limiting: +- **Rate Limit**: 100 requests per minute per IP +- **Burst Limit**: 20 requests per second +- **Headers**: `X-RateLimit-Limit`, `X-RateLimit-Remaining`, `X-RateLimit-Reset` + +--- + +# Pagination +Many list endpoints support pagination via query parameters: +- `pageNumber`: Page number (starting from 1) +- `pageSize`: Number of items per page (default: 50, max: 200) +- `sort`: Sort field (optional) +- `sortOrder`: Sort direction (`ASC` or `DESC`) + +Example: `GET /model?pageNumber=1&pageSize=10&sort=name&sortOrder=ASC` + +--- + +# Filtering +List endpoints support filtering via POST to `/filtered` sub-endpoints: + +
+Example Filter Request: Generic filter structure + +```json +{ + "searchContext": { + "applicationType": "stb" + }, + "pageNumber": 1, + "pageSize": 10, + "sortOrder": "ASC" +} +``` +
+ +--- + +*This documentation covers the core XconfAdmin API endpoints. For additional details on specific data structures and validation rules, refer to the service implementation or contact the development team.* \ No newline at end of file From 43198e23be3d563a6ba4a8058713684ecb979541 Mon Sep 17 00:00:00 2001 From: LakshmipriyaPurushan <60867402+LakshmipriyaPurushan@users.noreply.github.com> Date: Tue, 2 Dec 2025 11:14:17 +0530 Subject: [PATCH 02/23] Add files via upload --- docs/architecture.md | 189 +++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 189 insertions(+) create mode 100644 docs/architecture.md diff --git a/docs/architecture.md b/docs/architecture.md new file mode 100644 index 0000000..9347876 --- /dev/null +++ b/docs/architecture.md @@ -0,0 +1,189 @@ +# XConf System Architecture + +## System Architecture Diagram + +```mermaid +graph TB + subgraph "Client Layer" + RDK[RDK Devices] + UI[Web UI] + API[External APIs] + end + + subgraph "Service Layer" + subgraph "XConf Admin - Port: 9001" + AdminAPI[Admin API Handler] + AdminCache[Built-in Cache
Redis/In-Memory] + AdminLogic[Business Logic] + end + + subgraph "XConf WebConfig - Port: 9000" + WebAPI[WebConfig API] + WebCache[Built-in Cache
Redis/In-Memory] + RulesEngine[Rules Engine] + end + + subgraph "XConf UI - Port: 8081" + UIServer[UI Server & Proxy] + end + end + + subgraph "Data Layer" + Cassandra[(Cassandra Database)] + end + + subgraph "External Services" + SAT[SAT Service
Authentication] + IDP[IDP Service
Identity Provider] + Metrics[Prometheus
Metrics] + Tracing[OTEL Collector
Tracing] + end + + RDK -->|Configuration Requests| WebAPI + UI -->|User Interface| UIServer + API -->|Admin Operations| AdminAPI + + UIServer -->|Proxy Requests| AdminAPI + + WebAPI --> WebCache + WebCache -->|Cache Miss| RulesEngine + RulesEngine --> Cassandra + + AdminAPI --> AdminCache + AdminCache -->|Cache Miss| AdminLogic + AdminLogic --> Cassandra + + AdminLogic -->|Config Updates| WebCache + + AdminAPI --> SAT + AdminAPI --> IDP + WebAPI --> SAT + + AdminAPI --> Metrics + WebAPI --> Metrics + UIServer --> Metrics + + AdminAPI --> Tracing + WebAPI --> Tracing + + style AdminCache fill:#e1f5fe + style WebCache fill:#e1f5fe + style Cassandra fill:#f3e5f5 + style SAT fill:#fff3e0 + style IDP fill:#fff3e0 +``` + +## Deployment Architecture Diagram + +```mermaid +graph TB + subgraph "Load Balancer Layer" + LB[Load Balancer
NGINX/HAProxy] + end + + subgraph "Service Instances" + subgraph "XConf Admin Cluster" + XA1[Admin Instance 1
Built-in Cache] + XA2[Admin Instance 2
Built-in Cache] + end + + subgraph "XConf WebConfig Cluster" + WC1[WebConfig Instance 1
Built-in Cache] + WC2[WebConfig Instance 2
Built-in Cache] + end + + subgraph "XConf UI Cluster" + UI1[UI Instance 1] + UI2[UI Instance 2] + end + end + + subgraph "Data Layer" + C1[(Cassandra
Node 1)] + C2[(Cassandra
Node 2)] + C3[(Cassandra
Node 3)] + end + + subgraph "External Services" + SAT[SAT Service] + IDP[Identity Provider] + Prometheus[Prometheus] + OTEL[OTEL Collector] + end + + LB --> XA1 + LB --> XA2 + LB --> WC1 + LB --> WC2 + LB --> UI1 + LB --> UI2 + + XA1 --> C1 + XA2 --> C2 + WC1 --> C1 + WC2 --> C3 + + XA1 -.->|Cache Sync| XA2 + WC1 -.->|Cache Sync| WC2 + + XA1 --> SAT + XA2 --> SAT + WC1 --> SAT + WC2 --> SAT + + style XA1 fill:#e3f2fd + style XA2 fill:#e3f2fd + style WC1 fill:#e8f5e8 + style WC2 fill:#e8f5e8 +``` + +## How to Generate PNG + +To convert this Mermaid diagram to a PNG file, you can use several methods: + +### Method 1: Mermaid CLI +```bash +# Install Mermaid CLI +npm install -g @mermaid-js/mermaid-cli + +# Generate PNG from this markdown file +mmdc -i architecture.md -o architecture.png -t neutral -b white +``` + +### Method 2: Online Mermaid Live Editor +1. Visit: https://mermaid.live/ +2. Copy the mermaid code from above +3. Paste into the editor +4. Download as PNG + +### Method 3: VS Code Extension +1. Install "Mermaid Markdown Syntax Highlighting" extension +2. Open this file in VS Code +3. Right-click on the mermaid diagram +4. Select "Export Diagram" → PNG + +### Method 4: GitHub Integration +GitHub automatically renders Mermaid diagrams in markdown files, and you can screenshot or use browser tools to save as PNG. + +## Architecture Features + +### Built-in Cache Integration +- **XConf Admin**: Contains its own built-in cache (Redis/In-Memory) integrated within the service +- **XConf WebConfig**: Has its own built-in cache layer for high-performance device requests +- **No Separate Cache Layer**: Eliminated the standalone cache infrastructure + +### Enhanced Service Structure +- Each service shows internal components (API Handler, Cache, Business Logic) +- Cache operations are handled internally within each service +- Direct cache-to-database flow on cache misses + +### Simplified Data Flow +- **WebConfig**: API → Built-in Cache → Rules Engine → Cassandra +- **Admin**: API → Built-in Cache → Business Logic → Cassandra +- **Cross-Service**: Admin can invalidate WebConfig cache on configuration updates + +### Deployment Benefits +- **Reduced Infrastructure**: No need for separate Redis cluster management +- **Simplified Operations**: Cache management is part of service lifecycle +- **Better Performance**: In-process caching reduces network overhead +- **Cache Synchronization**: Services can sync cache state when needed \ No newline at end of file From 5b72a3c22e553ae3d619a34bb4aa07ca4bb7505d Mon Sep 17 00:00:00 2001 From: LakshmipriyaPurushan <60867402+LakshmipriyaPurushan@users.noreply.github.com> Date: Tue, 2 Dec 2025 11:22:37 +0530 Subject: [PATCH 03/23] Add files via upload --- docs/architecture.md | 175 ++++++++++++++----------------------------- 1 file changed, 56 insertions(+), 119 deletions(-) diff --git a/docs/architecture.md b/docs/architecture.md index 9347876..06883d4 100644 --- a/docs/architecture.md +++ b/docs/architecture.md @@ -4,137 +4,74 @@ ```mermaid graph TB - subgraph "Client Layer" - RDK[RDK Devices] - UI[Web UI] - API[External APIs] - end - - subgraph "Service Layer" - subgraph "XConf Admin - Port: 9001" - AdminAPI[Admin API Handler] - AdminCache[Built-in Cache
Redis/In-Memory] - AdminLogic[Business Logic] - end - - subgraph "XConf WebConfig - Port: 9000" - WebAPI[WebConfig API] - WebCache[Built-in Cache
Redis/In-Memory] - RulesEngine[Rules Engine] - end - - subgraph "XConf UI - Port: 8081" - UIServer[UI Server & Proxy] - end - end - - subgraph "Data Layer" - Cassandra[(Cassandra Database)] - end - - subgraph "External Services" - SAT[SAT Service
Authentication] - IDP[IDP Service
Identity Provider] - Metrics[Prometheus
Metrics] - Tracing[OTEL Collector
Tracing] - end - - RDK -->|Configuration Requests| WebAPI - UI -->|User Interface| UIServer - API -->|Admin Operations| AdminAPI - - UIServer -->|Proxy Requests| AdminAPI - - WebAPI --> WebCache - WebCache -->|Cache Miss| RulesEngine - RulesEngine --> Cassandra - - AdminAPI --> AdminCache - AdminCache -->|Cache Miss| AdminLogic - AdminLogic --> Cassandra - - AdminLogic -->|Config Updates| WebCache - - AdminAPI --> SAT - AdminAPI --> IDP - WebAPI --> SAT - - AdminAPI --> Metrics - WebAPI --> Metrics - UIServer --> Metrics - - AdminAPI --> Tracing - WebAPI --> Tracing - - style AdminCache fill:#e1f5fe - style WebCache fill:#e1f5fe - style Cassandra fill:#f3e5f5 - style SAT fill:#fff3e0 - style IDP fill:#fff3e0 + %% Clients + RDK[RDK Devices] + Operators[Operators/Admins] + + %% XConf Services + UI[XConf UI
Port: 8081
Web Interface] + Admin[XConf Admin
Port: 9001
API + Cache] + WebConfig[XConf WebConfig
Port: 9000
Data Service + Cache] + + %% Database + DB[(Cassandra
Database)] + + %% Flow + RDK --> WebConfig + Operators --> UI + UI --> Admin + Admin --> DB + WebConfig --> DB + + %% Styling + style UI fill:#e3f2fd + style Admin fill:#fff3e0 + style WebConfig fill:#e8f5e8 + style DB fill:#f3e5f5 ``` ## Deployment Architecture Diagram ```mermaid graph TB - subgraph "Load Balancer Layer" - LB[Load Balancer
NGINX/HAProxy] - end + %% Load Balancer + LB[Load Balancer] + + %% Service Instances + UI1[XConf UI] + UI2[XConf UI] - subgraph "Service Instances" - subgraph "XConf Admin Cluster" - XA1[Admin Instance 1
Built-in Cache] - XA2[Admin Instance 2
Built-in Cache] - end - - subgraph "XConf WebConfig Cluster" - WC1[WebConfig Instance 1
Built-in Cache] - WC2[WebConfig Instance 2
Built-in Cache] - end - - subgraph "XConf UI Cluster" - UI1[UI Instance 1] - UI2[UI Instance 2] - end - end + Admin1[XConf Admin] + Admin2[XConf Admin] - subgraph "Data Layer" - C1[(Cassandra
Node 1)] - C2[(Cassandra
Node 2)] - C3[(Cassandra
Node 3)] - end + Web1[XConf WebConfig] + Web2[XConf WebConfig] - subgraph "External Services" - SAT[SAT Service] - IDP[Identity Provider] - Prometheus[Prometheus] - OTEL[OTEL Collector] - end + %% Database Cluster + DB1[(Cassandra)] + DB2[(Cassandra)] + DB3[(Cassandra)] - LB --> XA1 - LB --> XA2 - LB --> WC1 - LB --> WC2 + %% Connections LB --> UI1 LB --> UI2 - - XA1 --> C1 - XA2 --> C2 - WC1 --> C1 - WC2 --> C3 - - XA1 -.->|Cache Sync| XA2 - WC1 -.->|Cache Sync| WC2 - - XA1 --> SAT - XA2 --> SAT - WC1 --> SAT - WC2 --> SAT - - style XA1 fill:#e3f2fd - style XA2 fill:#e3f2fd - style WC1 fill:#e8f5e8 - style WC2 fill:#e8f5e8 + LB --> Admin1 + LB --> Admin2 + LB --> Web1 + LB --> Web2 + + Admin1 --> DB1 + Admin2 --> DB2 + Web1 --> DB1 + Web2 --> DB3 + + %% Styling + style UI1 fill:#e3f2fd + style UI2 fill:#e3f2fd + style Admin1 fill:#fff3e0 + style Admin2 fill:#fff3e0 + style Web1 fill:#e8f5e8 + style Web2 fill:#e8f5e8 ``` ## How to Generate PNG From 4a376d1f33ef85b256744c2176b82814efee8a6c Mon Sep 17 00:00:00 2001 From: LakshmipriyaPurushan <60867402+LakshmipriyaPurushan@users.noreply.github.com> Date: Tue, 2 Dec 2025 11:30:46 +0530 Subject: [PATCH 04/23] Add files via upload --- docs/architecture.md | 218 +++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 218 insertions(+) diff --git a/docs/architecture.md b/docs/architecture.md index 06883d4..1474a02 100644 --- a/docs/architecture.md +++ b/docs/architecture.md @@ -74,6 +74,224 @@ graph TB style Web2 fill:#e8f5e8 ``` +## Process Flow Diagrams + +### Admin Create/Update Configuration Flow + +```mermaid +sequenceDiagram + participant Admin as Administrator + participant UI as XConf UI + participant AdminSvc as XConf Admin + participant Cache as Built-in Cache + participant DB as Cassandra + participant WebConfig as XConf WebConfig + + Note over Admin,WebConfig: Configuration Create/Update Process + + Admin->>UI: 1. Create/Update Config + Note right of Admin: Via Web Interface + + UI->>AdminSvc: 2. POST/PUT API Request + Note right of UI: /xconfAdminService/firmwareconfig + + AdminSvc->>AdminSvc: 3. Validate Request + Note right of AdminSvc: Auth, Schema, Rules + + AdminSvc->>DB: 4. Save Configuration + Note right of AdminSvc: Persist to Database + + DB-->>AdminSvc: 5. Confirm Save + + AdminSvc->>Cache: 6. Update Local Cache + Note right of AdminSvc: Refresh built-in cache + + AdminSvc->>WebConfig: 7. Invalidate Cache + Note right of AdminSvc: Notify WebConfig to refresh + + WebConfig->>WebConfig: 8. Clear Cache Entry + Note right of WebConfig: Remove cached config + + AdminSvc-->>UI: 9. Success Response + UI-->>Admin: 10. Confirmation + + Note over Admin,WebConfig: Configuration is now active for devices +``` + +### Device Configuration Request Flow + +```mermaid +sequenceDiagram + participant Device as RDK Device + participant WebConfig as XConf WebConfig + participant Cache as Built-in Cache + participant Rules as Rules Engine + participant DB as Cassandra + + Note over Device,DB: Device Configuration Request Process + + Device->>WebConfig: 1. Request Configuration + Note right of Device: GET /xconf/swu/stb?mac=XX&model=Y + + WebConfig->>Cache: 2. Check Cache + Note right of WebConfig: Look for cached result + + alt Cache Hit + Cache-->>WebConfig: 3a. Return Cached Config + Note right of Cache: Configuration found + else Cache Miss + Cache-->>WebConfig: 3b. Cache Miss + + WebConfig->>Rules: 4. Evaluate Rules + Note right of WebConfig: Apply device-specific rules + + Rules->>DB: 5. Query Configurations + Note right of Rules: Get firmware rules, etc. + + DB-->>Rules: 6. Return Config Data + + Rules->>Rules: 7. Process Rules + Note right of Rules: Match device to config + + Rules-->>WebConfig: 8. Computed Config + + WebConfig->>Cache: 9. Store in Cache + Note right of WebConfig: Cache for future requests + end + + WebConfig->>WebConfig: 10. Format Response + WebConfig-->>Device: 11. Return Configuration + + Note over Device,DB: Device applies received configuration +``` + +### Admin Rule Creation Flow + +```mermaid +sequenceDiagram + participant Admin as Administrator + participant UI as XConf UI + participant AdminSvc as XConf Admin + participant Cache as Built-in Cache + participant DB as Cassandra + + Note over Admin,DB: Firmware Rule Creation Process + + Admin->>UI: 1. Create Firmware Rule + Note right of Admin: Define targeting conditions + + UI->>AdminSvc: 2. POST /firmwarerule + Note right of UI: Submit rule definition + + AdminSvc->>AdminSvc: 3. Validate Rule + Note right of AdminSvc: Check syntax, references + + AdminSvc->>DB: 4. Check Dependencies + Note right of AdminSvc: Verify firmware config exists + + DB-->>AdminSvc: 5. Dependency Status + + alt Dependencies Valid + AdminSvc->>DB: 6a. Save Rule + DB-->>AdminSvc: 7a. Confirm Save + + AdminSvc->>Cache: 8a. Update Cache + Note right of AdminSvc: Add rule to cache + + AdminSvc-->>UI: 9a. Success Response + else Dependencies Invalid + AdminSvc-->>UI: 6b. Error Response + Note right of AdminSvc: Missing firmware config + end + + UI-->>Admin: 10. Result Notification +``` + +### Device Rule Evaluation Flow + +```mermaid +sequenceDiagram + participant Device as RDK Device + participant WebConfig as XConf WebConfig + participant Cache as Built-in Cache + participant Rules as Rules Engine + participant DB as Cassandra + + Note over Device,DB: Rule-Based Configuration Delivery + + Device->>WebConfig: 1. Configuration Request + Note right of Device: With device parameters + + WebConfig->>Cache: 2. Check Rule Cache + Note right of WebConfig: Look for matching rules + + alt Rules Cached + Cache-->>WebConfig: 3a. Return Cached Rules + else Rules Not Cached + Cache-->>WebConfig: 3b. Cache Miss + + WebConfig->>DB: 4. Load All Rules + Note right of WebConfig: Get firmware rules + + DB-->>WebConfig: 5. Return Rules + + WebConfig->>Cache: 6. Cache Rules + Note right of WebConfig: Store for reuse + end + + WebConfig->>Rules: 7. Evaluate Rules + Note right of Rules: Match device to rules by priority + + Rules->>Rules: 8. Apply Conditions + Note right of Rules: Check model, MAC, env, etc. + + alt Rule Matches + Rules->>DB: 9a. Get Firmware Config + DB-->>Rules: 10a. Return Config + Rules-->>WebConfig: 11a. Matched Configuration + else No Rule Match + Rules-->>WebConfig: 9b. Default Configuration + end + + WebConfig->>Cache: 12. Cache Result + Note right of WebConfig: Store computed config + + WebConfig-->>Device: 13. Return Configuration +``` + +### Cache Invalidation Flow + +```mermaid +sequenceDiagram + participant Admin as Administrator + participant AdminSvc as XConf Admin + participant AdminCache as Admin Cache + participant WebConfig as XConf WebConfig + participant WebCache as WebConfig Cache + participant DB as Cassandra + + Note over Admin,DB: Configuration Update with Cache Invalidation + + Admin->>AdminSvc: 1. Update Configuration + + AdminSvc->>DB: 2. Update Database + DB-->>AdminSvc: 3. Confirm Update + + AdminSvc->>AdminCache: 4. Invalidate Admin Cache + Note right of AdminSvc: Clear related cache entries + + AdminSvc->>WebConfig: 5. Send Cache Invalidation + Note right of AdminSvc: REST call or message + + WebConfig->>WebCache: 6. Clear Cache Entries + Note right of WebConfig: Remove affected configs + + WebConfig-->>AdminSvc: 7. Confirm Invalidation + AdminSvc-->>Admin: 8. Update Complete + + Note over Admin,DB: Next device request will get fresh config +``` + ## How to Generate PNG To convert this Mermaid diagram to a PNG file, you can use several methods: From 8f061e68ac62fb05a0e7ca80d540b9c067acb1ae Mon Sep 17 00:00:00 2001 From: LakshmipriyaPurushan <60867402+LakshmipriyaPurushan@users.noreply.github.com> Date: Tue, 2 Dec 2025 11:35:59 +0530 Subject: [PATCH 05/23] Add files via upload --- docs/architecture.md | 40 ++++++++++++++++++---------------------- 1 file changed, 18 insertions(+), 22 deletions(-) diff --git a/docs/architecture.md b/docs/architecture.md index 1474a02..00f71f2 100644 --- a/docs/architecture.md +++ b/docs/architecture.md @@ -125,7 +125,6 @@ sequenceDiagram participant Device as RDK Device participant WebConfig as XConf WebConfig participant Cache as Built-in Cache - participant Rules as Rules Engine participant DB as Cassandra Note over Device,DB: Device Configuration Request Process @@ -142,25 +141,23 @@ sequenceDiagram else Cache Miss Cache-->>WebConfig: 3b. Cache Miss - WebConfig->>Rules: 4. Evaluate Rules - Note right of WebConfig: Apply device-specific rules + WebConfig->>DB: 4. Query Configurations + Note right of WebConfig: Get firmware rules, etc. - Rules->>DB: 5. Query Configurations - Note right of Rules: Get firmware rules, etc. + DB-->>WebConfig: 5. Return Config Data - DB-->>Rules: 6. Return Config Data + WebConfig->>WebConfig: 6. Evaluate Rules + Note right of WebConfig: Match device to config by priority - Rules->>Rules: 7. Process Rules - Note right of Rules: Match device to config + WebConfig->>WebConfig: 7. Process Configuration + Note right of WebConfig: Apply device-specific logic - Rules-->>WebConfig: 8. Computed Config - - WebConfig->>Cache: 9. Store in Cache + WebConfig->>Cache: 8. Store in Cache Note right of WebConfig: Cache for future requests end - WebConfig->>WebConfig: 10. Format Response - WebConfig-->>Device: 11. Return Configuration + WebConfig->>WebConfig: 9. Format Response + WebConfig-->>Device: 10. Return Configuration Note over Device,DB: Device applies received configuration ``` @@ -214,7 +211,6 @@ sequenceDiagram participant Device as RDK Device participant WebConfig as XConf WebConfig participant Cache as Built-in Cache - participant Rules as Rules Engine participant DB as Cassandra Note over Device,DB: Rule-Based Configuration Delivery @@ -239,18 +235,18 @@ sequenceDiagram Note right of WebConfig: Store for reuse end - WebConfig->>Rules: 7. Evaluate Rules - Note right of Rules: Match device to rules by priority + WebConfig->>WebConfig: 7. Evaluate Rules + Note right of WebConfig: Match device to rules by priority - Rules->>Rules: 8. Apply Conditions - Note right of Rules: Check model, MAC, env, etc. + WebConfig->>WebConfig: 8. Apply Conditions + Note right of WebConfig: Check model, MAC, env, etc. alt Rule Matches - Rules->>DB: 9a. Get Firmware Config - DB-->>Rules: 10a. Return Config - Rules-->>WebConfig: 11a. Matched Configuration + WebConfig->>DB: 9a. Get Firmware Config + DB-->>WebConfig: 10a. Return Config + WebConfig->>WebConfig: 11a. Process Configuration else No Rule Match - Rules-->>WebConfig: 9b. Default Configuration + WebConfig->>WebConfig: 9b. Use Default Configuration end WebConfig->>Cache: 12. Cache Result From 6d61f1f7723d3a5e42cc784eeb372f80acd407e5 Mon Sep 17 00:00:00 2001 From: LakshmipriyaPurushan <60867402+LakshmipriyaPurushan@users.noreply.github.com> Date: Tue, 2 Dec 2025 11:43:06 +0530 Subject: [PATCH 06/23] Udate architecture documentation Updated various diagrams and process flows. --- docs/architecture.md | 50 -------------------------------------------- 1 file changed, 50 deletions(-) diff --git a/docs/architecture.md b/docs/architecture.md index 00f71f2..f33da0a 100644 --- a/docs/architecture.md +++ b/docs/architecture.md @@ -288,53 +288,3 @@ sequenceDiagram Note over Admin,DB: Next device request will get fresh config ``` -## How to Generate PNG - -To convert this Mermaid diagram to a PNG file, you can use several methods: - -### Method 1: Mermaid CLI -```bash -# Install Mermaid CLI -npm install -g @mermaid-js/mermaid-cli - -# Generate PNG from this markdown file -mmdc -i architecture.md -o architecture.png -t neutral -b white -``` - -### Method 2: Online Mermaid Live Editor -1. Visit: https://mermaid.live/ -2. Copy the mermaid code from above -3. Paste into the editor -4. Download as PNG - -### Method 3: VS Code Extension -1. Install "Mermaid Markdown Syntax Highlighting" extension -2. Open this file in VS Code -3. Right-click on the mermaid diagram -4. Select "Export Diagram" → PNG - -### Method 4: GitHub Integration -GitHub automatically renders Mermaid diagrams in markdown files, and you can screenshot or use browser tools to save as PNG. - -## Architecture Features - -### Built-in Cache Integration -- **XConf Admin**: Contains its own built-in cache (Redis/In-Memory) integrated within the service -- **XConf WebConfig**: Has its own built-in cache layer for high-performance device requests -- **No Separate Cache Layer**: Eliminated the standalone cache infrastructure - -### Enhanced Service Structure -- Each service shows internal components (API Handler, Cache, Business Logic) -- Cache operations are handled internally within each service -- Direct cache-to-database flow on cache misses - -### Simplified Data Flow -- **WebConfig**: API → Built-in Cache → Rules Engine → Cassandra -- **Admin**: API → Built-in Cache → Business Logic → Cassandra -- **Cross-Service**: Admin can invalidate WebConfig cache on configuration updates - -### Deployment Benefits -- **Reduced Infrastructure**: No need for separate Redis cluster management -- **Simplified Operations**: Cache management is part of service lifecycle -- **Better Performance**: In-process caching reduces network overhead -- **Cache Synchronization**: Services can sync cache state when needed \ No newline at end of file From 43c29baa12f04ed76a9690d6ed5d6a6b3982e1d7 Mon Sep 17 00:00:00 2001 From: LakshmipriyaPurushan <60867402+LakshmipriyaPurushan@users.noreply.github.com> Date: Mon, 19 Jan 2026 21:34:59 +0530 Subject: [PATCH 07/23] Add files via upload --- docs/overview1.md | 653 ++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 653 insertions(+) create mode 100644 docs/overview1.md diff --git a/docs/overview1.md b/docs/overview1.md new file mode 100644 index 0000000..dace0b6 --- /dev/null +++ b/docs/overview1.md @@ -0,0 +1,653 @@ +# XConf System Overview + +## Table of Contents +- [Overview](#overview) +- [System Architecture](#system-architecture) +- [Core Components](#core-components) +- [Process Flow Diagrams](#process-flow-diagrams) +- [Use Cases](#use-cases) +- [API Overview](#api-overview) +- [Configuration Management](#configuration-management) +- [Deployment Architecture](#deployment-architecture) +- [Security Model](#security-model) +- [Getting Started](#getting-started) + +## Overview + +XConf is a comprehensive configuration management platform designed for RDK (Reference Design Kit) devices. It provides centralized control over device configurations, firmware updates, telemetry settings, and feature management across large-scale RDK deployments. The system is built with Go and follows a microservices architecture with three main components working together to deliver a complete configuration management solution. + +### Key Features + +- **Centralized Configuration Management**: XConf serves as a single point of control for all device configurations across large-scale RDK deployments. This unified approach eliminates configuration fragmentation and ensures consistency across thousands of devices in the field, providing operators with a comprehensive view of their entire device ecosystem. + +- **Firmware Management**: The platform enables operators to control firmware distribution and updates with sophisticated canary deployment strategies. This includes percentage-based rollouts, device cohort targeting, and emergency rollback procedures to minimize risk during firmware updates while ensuring rapid deployment of security patches and feature enhancements. + +- **Telemetry Services**: XConf manages comprehensive telemetry profiles and data collection policies, allowing operators to configure what data is collected, how frequently it's gathered, and where it's uploaded. This enables data-driven insights into device performance and user behavior patterns while maintaining privacy compliance and optimizing bandwidth usage. + +- **Device Control Manager (DCM)**: The DCM component handles critical device control settings and log upload policies, providing granular control over device behavior, log collection schedules, and diagnostic data management. This ensures proper device operation and facilitates troubleshooting when issues arise in production environments. + +- **Feature Management (RFC)**: Through the RDK Feature Control system, operators can control feature flags and rules with priority-based evaluation, enabling safe feature rollouts and A/B testing scenarios. Features can be activated for specific device cohorts or gradually rolled out using percentage-based distribution with real-time monitoring and rollback capabilities. + +- **Authentication and Authorization**: Robust security mechanisms provide JWT-based authentication with comprehensive role-based access control, ensuring that only authorized personnel can modify configurations. All changes are properly audited and tracked, maintaining complete operational transparency and compliance requirements. + +- **RESTful APIs**: The system exposes comprehensive RESTful APIs for all operations, enabling programmatic access and integration with existing operational tools and workflows. This API-first approach supports automation and custom tooling development while maintaining consistent interface standards across all components. + +- **Metrics and Monitoring**: Built-in observability capabilities include Prometheus metrics collection and OpenTelemetry distributed tracing support, providing complete visibility into system performance and operational health across all components. This enables proactive monitoring and rapid issue resolution. + +- **High Availability**: The platform achieves operational resilience through distributed locking mechanisms and robust data persistence strategies that enable scalable operations across multiple data centers while maintaining data consistency and system reliability with optimized response times. + +## System Architecture + +The XConf system follows a three-tier architecture with clear separation of responsibilities: + +```mermaid +graph TB + subgraph "Client Layer" + RDK[RDK Devices
Config Requests] + WebUI[Web UI
User Interface] + ExtAPI[External APIs
Admin Operations] + end + + subgraph "Service Layer" + WebConfig[XConf WebConfig
Port: 9000
Device API] + UIServer[XConf UI Server
Port: 8081
Web Interface] + Admin[XConf Admin
Port: 9001
Management API] + end + + subgraph "Data Layer" + Cassandra[(Cassandra DB
Primary Storage)] + end + + subgraph "External Services" + SAT[SAT Service
Auth Tokens] + IDP[Identity Provider
User Auth] + Prometheus[Prometheus
Metrics] + OTEL[OTEL Collector
Tracing] + end + + %% Client to Service connections + RDK -->|Configuration Queries| WebConfig + WebUI -->|User Interface| UIServer + ExtAPI -->|Admin Operations| Admin + + %% Service to Service connections + UIServer -->|Proxy Requests| Admin + + %% Service to Data connections + WebConfig --> Cassandra + Admin --> Cassandra + + %% Service to External connections + WebConfig --> SAT + Admin --> SAT + Admin --> IDP + WebConfig --> Prometheus + Admin --> Prometheus + WebConfig --> OTEL + Admin --> OTEL + + %% Styling for better contrast on white background + classDef clientLayer fill:#e1f5fe,stroke:#01579b,stroke-width:2px,color:#000 + classDef serviceLayer fill:#f3e5f5,stroke:#4a148c,stroke-width:2px,color:#000 + classDef dataLayer fill:#e8f5e8,stroke:#1b5e20,stroke-width:2px,color:#000 + classDef externalLayer fill:#fff3e0,stroke:#e65100,stroke-width:2px,color:#000 + + class RDK,WebUI,ExtAPI clientLayer + class WebConfig,UIServer,Admin serviceLayer + class Cassandra dataLayer + class SAT,IDP,Prometheus,OTEL externalLayer +``` + +### Architecture Principles +- **Microservices Design**: Each component has a specific responsibility +- **Stateless Services**: All services are stateless for horizontal scalability +- **Event-Driven**: Asynchronous processing for configuration changes +- **Security First**: Multiple layers of authentication and authorization +- **Observability**: Built-in metrics, logging, and distributed tracing + +## Core Components + +### 1. XConf Admin +**Purpose**: Administrative backend service for configuration management + +**Key Capabilities**: +- Configuration CRUD operations (firmware, DCM, telemetry, RFC) +- Rule-based configuration management with priority handling +- User authentication and authorization +- Change management and audit logging +- API gateway for administrative functions + +**Main Modules**: +- `adminapi/`: REST API handlers and routing +- `auth/`: Authentication and authorization services +- `firmware/`: Firmware configuration management +- `dcm/`: Device Control Manager settings +- `telemetry/`: Telemetry profile management +- `rfc/`: RDK Feature Control management +- `queries/`: Query and reporting services + +### 2. XConf WebConfig +**Purpose**: Data service for RDK devices to retrieve configurations + +**Key Capabilities**: +- High-performance configuration delivery to RDK devices +- Rule engine for dynamic configuration evaluation +- Firmware version determination and distribution control +- Telemetry and DCM settings delivery +- Health checks and diagnostics + +**Main Modules**: +- `dataapi/`: Device-facing API endpoints +- `rulesengine/`: Configuration rule evaluation +- `db/`: Database abstraction and caching +- `security/`: Request validation and security +- `tracing/`: Distributed tracing implementation + +### 3. XConf UI +**Purpose**: Web-based user interface for system administration + +**Key Capabilities**: +- Interactive web interface for configuration management +- Proxy service to XConf Admin backend +- Static asset serving (HTML, CSS, JavaScript) +- User session management + +**Main Modules**: +- `app/`: Angular-based web application +- `server/`: Go-based proxy server +- `templates/`: HTML templates + +## Process Flow Diagrams + +### Device Configuration Request Flow + +```mermaid +sequenceDiagram + participant RDK as RDK Device + participant WC as XConf WebConfig + participant DB as Database + + RDK->>WC: GET /xconf/swu/stb?eStbMac=...&model=... + + WC->>DB: Query config rules + DB-->>WC: Rules & settings + + Note over WC: Evaluate rules
Apply security
Generate JSON + + WC-->>RDK: Configuration Response + + Note over RDK,WC: Response includes firmware version,
download URL, DCM settings, etc.
Device parameters include MAC address,
model, environment, etc. +``` + +### Administrative Configuration Update Flow + +```mermaid +sequenceDiagram + participant Admin as Administrator + participant UI as XConf UI + participant API as XConf Admin + participant DB as Database + + Admin->>UI: Update firmware rule + UI->>API: POST /xconfAdminService/firmwarerule + + Note over API: Validate auth & rule + + API->>DB: Store updated rule + + API-->>UI: Confirmation response + UI-->>Admin: Success notification + + Note over Admin,API: Updated configuration is immediately
available for next device requests +``` + +### Feature Flag Management Flow + +```mermaid +sequenceDiagram + participant Admin as Administrator + participant API as XConf Admin + participant RDK as RDK Device + participant WC as XConf WebConfig + + Admin->>API: Create RFC feature rule + + Note over API: Validate rule conditions
& set priority + + RDK->>WC: Request feature settings + + Note over WC: Evaluate RFC rules by priority
Apply percentage-based rollout + + WC-->>RDK: Feature configuration + + Note over RDK: Apply settings based on config + + Note over Admin,RDK: Flow Summary:
1. Administrator creates RFC feature rules with conditions and rollout percentages
2. RDK devices periodically request feature settings from XConf WebConfig
3. WebConfig evaluates rules by priority and applies percentage-based distribution
4. Devices receive feature configuration and apply settings accordingly +``` + +## Use Cases + +The XConf platform supports diverse operational scenarios across different organizational roles and responsibilities. Each use case demonstrates the platform's capability to address specific configuration management challenges in RDK device deployments. + +### Use Case 1: Firmware Management +**Primary Actors**: Operations Team, DevOps Team +**Supporting Systems**: XConf Admin, XConf WebConfig, Device Fleet + +**Scenario**: Operations teams need to roll out new firmware versions to thousands of RDK devices while minimizing risk and ensuring system stability during the deployment process. + +**Process Flow**: +1. **Upload Firmware Configuration**: Operations team uploads firmware version metadata including download URLs, checksums, and compatibility information through XConf Admin interface +2. **Create Deployment Rules**: Define targeting rules based on device models, environments, and partner configurations with conditional logic +3. **Configure Canary Strategy**: Implement percentage-based rollout starting with 1% of devices, gradually increasing to full deployment +4. **Monitor Deployment Progress**: Track firmware adoption rates, device health metrics, and rollback triggers through real-time dashboards +5. **Emergency Response**: Execute rapid rollback procedures if issues are detected during deployment + +**Expected Outcomes**: Controlled firmware distribution with minimized risk, comprehensive deployment visibility, and rapid issue resolution capabilities. + +### Use Case 2: Device Control Manager (DCM) Configuration +**Primary Actors**: Support Team, Operations Team +**Supporting Systems**: XConf Admin, Device Diagnostic Systems + +**Scenario**: Support teams require granular control over device log collection, diagnostic data uploads, and device behavior parameters to facilitate troubleshooting and maintain operational visibility. + +**Process Flow**: +1. **Define Log Upload Policies**: Configure log collection schedules, retention policies, and upload destinations based on device types and support requirements +2. **Configure Device Settings**: Set device behavior parameters including reboot schedules, diagnostic intervals, and maintenance windows +3. **Create Conditional Formulas**: Implement rule-based logic for dynamic device control based on device health, network conditions, and operational requirements +4. **Deploy Settings**: Push DCM configurations to targeted device populations with validation and rollback capabilities +5. **Monitor Collection**: Track log upload success rates, diagnostic data quality, and device compliance with configured policies + +**Expected Outcomes**: Automated log collection, improved troubleshooting capabilities, and enhanced device operational visibility. + +### Use Case 3: Feature Flag Control (RFC) +**Primary Actors**: Product Team, QA Team +**Supporting Systems**: XConf Admin, XConf WebConfig, Feature Management System + +**Scenario**: Product teams need to implement safe feature rollouts, conduct A/B testing, and manage experimental features across device populations with precise targeting and rollback capabilities. + +**Process Flow**: +1. **Create Feature Control Rules**: Define feature activation conditions based on device characteristics, user segments, and deployment criteria +2. **Configure Rollout Strategy**: Implement percentage-based feature distribution with gradual increase and statistical validation +3. **Set Feature Parameters**: Configure feature-specific settings, default values, and behavioral parameters for targeted device groups +4. **Monitor Feature Performance**: Track feature adoption rates, user engagement metrics, and system performance impact +5. **Optimize and Scale**: Adjust feature parameters based on performance data and scale successful features to broader device populations + +**Expected Outcomes**: Safe feature experimentation, data-driven feature decisions, and controlled feature deployment with rapid iteration capabilities. + +### Use Case 4: Telemetry Management +**Primary Actors**: Analytics Team, Product Team +**Supporting Systems**: XConf Admin, Data Collection Infrastructure, Analytics Platform + +**Scenario**: Analytics teams require comprehensive telemetry data collection from device populations to support product insights, performance optimization, and business intelligence initiatives. + +**Process Flow**: +1. **Define Collection Profiles**: Configure telemetry metrics, collection intervals, and data schemas based on analytical requirements +2. **Target Device Segments**: Create targeting rules for different device populations, user segments, and geographical regions +3. **Configure Upload Schedules**: Set data upload frequencies, bandwidth optimization, and privacy compliance parameters +4. **Validate Data Quality**: Implement data validation rules, quality checks, and error handling procedures +5. **Generate Analytics Reports**: Process collected telemetry data for business insights, performance optimization, and product development + +**Expected Outcomes**: Comprehensive device insights, data-driven product decisions, and optimized user experience based on telemetry analytics. + +### Use Case 5: Environment Configuration Management +**Primary Actors**: DevOps Team, Infrastructure Team +**Supporting Systems**: XConf Admin, CI/CD Pipeline, Environment Management Tools + +**Scenario**: DevOps teams need to maintain configuration consistency across development, staging, and production environments while enabling seamless configuration promotion and environment-specific customizations. + +**Process Flow**: +1. **Define Environment Rules**: Create environment-specific configuration rules with inheritance patterns and override capabilities +2. **Configure Version Management**: Implement configuration versioning with promotion workflows and rollback procedures +3. **Enforce Policy Compliance**: Set automated policy validation, compliance checks, and approval workflows for configuration changes +4. **Promote Configurations**: Execute seamless configuration promotion from development through staging to production environments +5. **Monitor Configuration Drift**: Track configuration differences across environments and implement drift detection and correction + +**Expected Outcomes**: Consistent multi-environment configuration management, streamlined deployment workflows, and reduced configuration-related issues. + +### Use Case 6: Real-time Device Configuration +**Primary Actors**: RDK Devices, Automated Systems +**Supporting Systems**: XConf WebConfig, Device Management Platform, Network Infrastructure + +**Scenario**: RDK devices automatically request and receive configuration updates, apply settings based on their characteristics, and report status back to the platform for monitoring and compliance verification. + +**Process Flow**: +1. **Request Configurations**: Devices periodically query XConf WebConfig for current configuration updates based on device parameters +2. **Receive Targeted Settings**: Platform delivers device-specific configurations including firmware versions, feature settings, and operational parameters +3. **Apply Configuration Changes**: Devices validate and apply received configurations with appropriate error handling and rollback capabilities +4. **Report Status Updates**: Devices provide feedback on configuration application success, system health, and operational status +5. **Maintain Compliance**: Continuous monitoring ensures devices maintain compliance with current configuration policies + +**Expected Outcomes**: Automated device configuration management, real-time compliance monitoring, and seamless configuration distribution across device populations. + +### Use Case 7: System Monitoring and Observability +**Primary Actors**: Operations Team, Support Team, DevOps Team +**Supporting Systems**: Prometheus, OTEL Collector, Monitoring Dashboards, Alert Management + +**Scenario**: Cross-functional teams require comprehensive monitoring of system health, deployment progress, performance metrics, and operational status through integrated dashboards and proactive alerting mechanisms. + +**Process Flow**: +1. **Configure Monitoring Infrastructure**: Set up comprehensive metrics collection, distributed tracing, and log aggregation across all system components +2. **Create Performance Dashboards**: Implement real-time dashboards showing system health, device connectivity, and configuration distribution metrics +3. **Define Alert Policies**: Configure intelligent alerting for system anomalies, performance degradation, and operational issues +4. **Track Deployment Progress**: Monitor configuration rollouts, feature adoption rates, and deployment success metrics +5. **Investigate and Resolve Issues**: Use integrated monitoring data for rapid issue identification, root cause analysis, and resolution tracking + +**Expected Outcomes**: Proactive system monitoring, rapid issue detection and resolution, and comprehensive operational visibility across the entire XConf platform. + +## API Overview + +### XConf Admin API (`/xconfAdminService`) +**Authentication**: JWT tokens or session-based authentication +**Base URL**: `http://host:9001/xconfAdminService` + +**Key Endpoints**: +- `GET/POST/PUT/DELETE /firmwareconfig` - Firmware configuration management +- `GET/POST/PUT/DELETE /firmwarerule` - Firmware rule management +- `GET/POST/PUT/DELETE /dcm/formula` - DCM formula management +- `GET/POST/PUT/DELETE /telemetry/profile` - Telemetry profile management +- `GET/POST/PUT/DELETE /rfc/feature` - Feature rule management +- `GET /queries/environments` - Environment queries +- `POST /auth/basic` - Basic authentication +- `GET /provider` - Authentication provider info + +### XConf WebConfig API (`/xconf`) +**Authentication**: Device-based validation +**Base URL**: `http://host:9000/xconf` + +**Key Endpoints**: +- `GET /swu/stb` - Firmware configuration for STB devices +- `GET /loguploader/getSettings` - Log upload settings +- `GET /rfc/feature/getSettings` - Feature settings +- `GET /telemetry/getTelemetryProfiles` - Telemetry profiles +- `GET /dcm/getSettings` - DCM settings + +### Request/Response Examples + +**Device Firmware Request**: +```bash +GET /xconf/swu/stb?eStbMac=AA:BB:CC:DD:EE:FF&model=MODEL_X&env=PROD +``` + +**Firmware Response**: +```json +{ + "firmwareVersion": "2.1.0", + "firmwareDownloadURL": "https://firmware.example.com/firmware-2.1.0.bin", + "firmwareFilename": "firmware-2.1.0.bin", + "rebootImmediately": false, + "forceHttp": false +} +``` + +## Configuration Management + +XConf utilizes HOCON (Human-Optimized Config Object Notation) configuration files that provide comprehensive control over all system components. The platform supports three distinct configuration profiles optimized for different operational responsibilities. + +### Configuration Architecture + +```mermaid +graph TB + subgraph "Configuration Sources" + AdminConf[XConf Admin Config
xconfadmin.conf] + WebConfigConf[XConf WebConfig Config
xconfwebconfig.conf] + UIConf[XConf UI Config
xconfui.conf] + end + + subgraph "Configuration Categories" + ServerConfig[Server Configuration
• Port bindings
• Timeouts
• Metrics] + ServiceConfig[Service Integration
• SAT Authentication
• External APIs
• Feature toggles] + DataConfig[Data Layer
• Cassandra clusters
• Cache settings
• Connection pools] + SecurityConfig[Security Settings
• JWT tokens
• TLS certificates
• Authentication] + end + + subgraph "Runtime Environment" + EnvVars[Environment Variables
• SAT_CLIENT_ID
• DATABASE_PASSWORD
• SECURITY_TOKEN_KEY] + Deployment[Deployment Context
• Development
• Staging
• Production] + end + + AdminConf --> ServerConfig + AdminConf --> ServiceConfig + AdminConf --> DataConfig + AdminConf --> SecurityConfig + + WebConfigConf --> ServerConfig + WebConfigConf --> ServiceConfig + WebConfigConf --> DataConfig + + UIConf --> ServerConfig + UIConf --> ServiceConfig + + EnvVars --> ServiceConfig + EnvVars --> SecurityConfig + Deployment --> ServiceConfig + + %% Styling + classDef configSource fill:#e3f2fd,stroke:#0277bd,stroke-width:2px,color:#000 + classDef configCategory fill:#f3e5f5,stroke:#6a1b9a,stroke-width:2px,color:#000 + classDef runtime fill:#e8f5e8,stroke:#2e7d32,stroke-width:2px,color:#000 + + class AdminConf,WebConfigConf,UIConf configSource + class ServerConfig,ServiceConfig,DataConfig,SecurityConfig configCategory + class EnvVars,Deployment runtime +``` + +### XConf Admin Configuration + +**Primary Responsibilities**: Administrative backend operations, user authentication, and configuration management workflows. + +**Key Configuration Areas**: +- **Service Integration**: Comprehensive external service connections including SAT authentication, Identity Provider (IDP), device services, account management, and tagging systems +- **Canary Management**: Advanced deployment controls with timezone support, percentage-based rollouts, and partner-specific configurations +- **Authentication Framework**: JWT-based security with configurable token validation and role-based access control +- **Cache Strategy**: Multi-level caching with configurable refresh cycles, distributed locking mechanisms, and performance optimization +- **Database Operations**: Cassandra cluster management with SSL support, connection pooling, and query optimization settings +- **Tracing & Observability**: OpenTelemetry integration with configurable endpoints and distributed tracing capabilities + +**Notable Features**: +- Supports 20+ external service integrations with individual timeout and retry configurations +- Configurable canary deployment windows with timezone awareness +- Advanced distributed locking for concurrent operations +- Comprehensive audit logging and security token management + +### XConf WebConfig Configuration + +**Primary Responsibilities**: High-performance device-facing API operations and configuration delivery optimization. + +**Key Configuration Areas**: +- **Performance Optimization**: Enhanced caching strategies with group service integration, cache expiration policies, and connection pooling +- **Device Integration**: Specialized device service connections with model-specific configurations and validation rules +- **Feature Toggles**: Granular control over RFC features, firmware penetration metrics, and experimental capabilities +- **Security Enhancements**: Device-specific authentication, token management for firmware delivery, and protocol-based security controls +- **Data Processing**: Advanced configuration preprocessing, IP address parsing, and network mask management +- **Metrics Collection**: Device interaction metrics, model-based request tracking, and performance monitoring + +**Notable Features**: +- Device-optimized caching with 4-hour refresh cycles for group services +- Security token integration for firmware download protection +- Advanced IP address processing with IPv4/IPv6 network mask support +- RFC precooking capabilities for improved response times +- Model-specific feature enablement for targeted device populations + +### XConf UI Configuration + +**Primary Responsibilities**: Web-based administration interface and proxy service management. + +**Key Configuration Areas**: +- **Proxy Architecture**: Streamlined configuration for backend service integration through XConf Admin API +- **Web Server Settings**: Port configuration, static asset management, and web root directory specification +- **Logging Framework**: Structured logging with file-based output and caller information tracking +- **Development Support**: Simplified configuration for development environments and debugging capabilities + +**Notable Features**: +- Lightweight configuration focused on web interface requirements +- Automatic proxy routing to XConf Admin backend services +- Development-friendly logging with detailed caller information +- Minimal external dependencies for rapid deployment + +### Configuration Management Framework + +**Environment Variable Integration**: The platform leverages secure environment variable injection for sensitive configuration parameters including SAT_CLIENT_ID and SAT_CLIENT_SECRET for service-to-service authentication credentials, DATABASE_USER and DATABASE_PASSWORD for Cassandra database authentication, and SECURITY_TOKEN_KEY for JWT token signing and validation operations. + +**Configuration Validation & Processing**: XConf implements comprehensive HOCON format validation with nested object support, automatic environment variable substitution with intelligent default fallbacks, proactive service dependency validation and health checking mechanisms, and real-time configuration drift detection with automated alerting capabilities to ensure operational consistency. + +**Multi-Environment Deployment Patterns**: The system supports distinct deployment configurations optimized for different operational contexts. Development environments utilize local configuration profiles with disabled external services and enhanced debug logging for rapid development cycles. Staging environments implement production-like configurations with dedicated test service endpoints and comprehensive monitoring integration for pre-production validation. Production deployments feature full external service integration with performance-optimized settings and enterprise-grade security hardening measures. + +**Advanced Rule Engine & Logic**: XConf's configuration engine supports sophisticated conditional configuration mechanisms using complex boolean expressions for environment-specific settings, priority-based evaluation systems with hierarchical configuration override capabilities, temporal controls enabling time-based configuration activation and automated feature scheduling, and percentage distribution algorithms providing gradual rollout capabilities with statistical distribution controls for safe deployment practices. + +**Comprehensive Configuration Scope**: The platform manages diverse configuration types including firmware management systems for version control and deployment strategies, DCM policies governing log collection schedules and device behavior parameters, RFC features enabling feature flag management and A/B testing configurations, telemetry profiles defining data collection policies and analytics configurations, and security policies establishing authentication requirements and access control matrices across all system components. + +## Deployment Architecture + +XConf's production deployment architecture follows enterprise-grade patterns with multiple layers of redundancy, horizontal scaling capabilities, and comprehensive observability integration. The platform is designed to handle high-throughput device communication while maintaining configuration consistency and operational reliability across distributed environments. + +### Recommended Deployment Pattern + +```mermaid +graph TB + subgraph "Load Balancer Layer" + LB[Load Balancer
NGINX/HAProxy] + end + + subgraph "Service Instances" + XA1[XConf Admin
Instance 1] + XA2[XConf Admin
Instance 2] + WC1[XConf WebConfig
Instance 1] + WC2[XConf WebConfig
Instance 2] + UI1[XConf UI
Instance 1] + UI2[XConf UI
Instance 2] + end + + subgraph "Data Layer" + C1[(Cassandra
Node 1)] + C2[(Cassandra
Node 2)] + C3[(Cassandra
Node 3)] + end + + subgraph "External Services" + SAT[SAT Service] + IDP[Identity Provider] + Prometheus[Prometheus] + OTEL[OTEL Collector] + end + + LB --> XA1 + LB --> XA2 + LB --> WC1 + LB --> WC2 + LB --> UI1 + LB --> UI2 + + XA1 --> C1 + XA2 --> C2 + WC1 --> C1 + WC2 --> C3 + + XA1 --> SAT + XA2 --> SAT + WC1 --> SAT + WC2 --> SAT +``` + +The deployment architecture implements a layered approach where the load balancer efficiently distributes incoming traffic across multiple service instances based on request type and current system load. Each service type operates multiple instances to ensure high availability and fault tolerance, with automatic failover mechanisms protecting against individual service failures. The Cassandra cluster provides distributed data storage with automatic replication and sharding capabilities, ensuring data consistency and availability even during node failures. External services integration encompasses authentication systems for secure access control, comprehensive monitoring infrastructure for operational visibility, and distributed tracing capabilities for performance optimization and troubleshooting support. + +### Infrastructure Requirements +- **Compute**: Minimum 2 CPU cores, 4GB RAM per service instance +- **Storage**: SSD storage for database with replication +- **Network**: High-bandwidth connection for firmware distribution +- **Database**: Cassandra cluster with minimum 3 nodes for HA + +### Scaling Considerations +- **Horizontal Scaling**: Stateless services support easy horizontal scaling +- **Database Sharding**: Cassandra provides automatic sharding and replication +- **Load Distribution**: Geographic distribution for global deployments + +## Security Model + +### Authentication Layers +1. **Service-to-Service**: SAT (Security Access Token) based authentication +2. **User Authentication**: Integration with enterprise identity providers +3. **Device Authentication**: MAC address and certificate-based validation +4. **API Security**: JWT tokens with role-based access control + +### Authorization Framework +- **Entity-Based Permissions**: Granular permissions per configuration entity +- **Role-Based Access Control**: Predefined roles with specific capabilities +- **Operation-Level Security**: Read/write permissions per API endpoint +- **Environment Isolation**: Strict separation between environments + +### Security Features +- **Token Validation**: Comprehensive JWT token validation and refresh +- **Request Sanitization**: Input validation and sanitization +- **Audit Logging**: Complete audit trail for all configuration changes +- **Secure Communication**: HTTPS/TLS for all service communications + +## Getting Started + +### Prerequisites +- **Go 1.23+**: For building and running the services +- **Cassandra 3.11+**: For data persistence +- **Node.js 24.1.0+**: For UI development +- **Git**: For source code management + +### Quick Start + +1. **Clone Repositories**: +```bash +git clone https://github.com/rdkcentral/xconfadmin.git +git clone https://github.com/rdkcentral/xconfui.git +git clone https://github.com/rdkcentral/xconfwebconfig.git +``` + +2. **Start Database**: +```bash +# Start Cassandra and create schema +cassandra -f & +cqlsh -f xconfwebconfig-main/db/db_init.cql +``` + +3. **Configure Services**: +```bash +# Copy and modify configuration files +cp xconfadmin/config/sample_xconfadmin.conf /etc/xconf/xconfadmin.conf +cp xconfwebconfig-main/config/sample_xconfwebconfig.conf /etc/xconf/xconfwebconfig.conf +cp xconfui-main/config/sample_xconfui.conf /etc/xconf/xconfui.conf +``` + +4. **Build and Run Services**: +```bash +# Build XConf Admin +cd xconfadmin && make build +./bin/xconfadmin-linux-amd64 -f /etc/xconf/xconfadmin.conf & + +# Build XConf WebConfig +cd xconfwebconfig-main && make build +./bin/xconfwebconfig-linux-amd64 -f /etc/xconf/xconfwebconfig.conf & + +# Build and Run XConf UI +cd xconfui-main +npm install && grunt install +go run *.go -f /etc/xconf/xconfui.conf & +``` + +5. **Access the System**: +- **Admin UI**: http://localhost:8081 +- **Admin API**: http://localhost:9001/xconfAdminService +- **WebConfig API**: http://localhost:9000/xconf + +### Configuration Tips +- Set environment variables for SAT_CLIENT_ID, SAT_CLIENT_SECRET, and SECURITY_TOKEN_KEY +- Configure appropriate log levels for production deployments +- Enable metrics and tracing for production monitoring +- Use environment-specific configuration files +- Implement proper backup strategies for Cassandra + +### Development Workflow +1. Make changes to source code +2. Run unit tests: `go test ./...` +3. Build and test locally +4. Deploy to staging environment +5. Run integration tests +6. Deploy to production with canary rollout + + +This overview provides a comprehensive understanding of the XConf system architecture, components, and operational patterns. For detailed API documentation, refer to the individual API documentation files in each component directory. From ce8e5241662a76850af2fa996e4705ee91d940c0 Mon Sep 17 00:00:00 2001 From: LakshmipriyaPurushan <60867402+LakshmipriyaPurushan@users.noreply.github.com> Date: Mon, 19 Jan 2026 21:58:14 +0530 Subject: [PATCH 08/23] Add files via upload --- docs/overview2.md | 653 ++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 653 insertions(+) create mode 100644 docs/overview2.md diff --git a/docs/overview2.md b/docs/overview2.md new file mode 100644 index 0000000..af0fe58 --- /dev/null +++ b/docs/overview2.md @@ -0,0 +1,653 @@ +# XConf System Overview + +## Table of Contents +- [Overview](#overview) +- [System Architecture](#system-architecture) +- [Core Components](#core-components) +- [Process Flow Diagrams](#process-flow-diagrams) +- [Use Cases](#use-cases) +- [API Overview](#api-overview) +- [Configuration Management](#configuration-management) +- [Deployment Architecture](#deployment-architecture) +- [Security Model](#security-model) +- [Getting Started](#getting-started) + +## Overview + +XConf is a comprehensive configuration management platform designed for RDK (Reference Design Kit) devices. It provides centralized control over device configurations, firmware updates, telemetry settings, and feature management across large-scale RDK deployments. The system is built with Go and follows a microservices architecture with three main components working together to deliver a complete configuration management solution. + +### Key Features + +- **Centralized Configuration Management**: XConf serves as a single point of control for all device configurations across large-scale RDK deployments. This unified approach eliminates configuration fragmentation and ensures consistency across thousands of devices in the field, providing operators with a comprehensive view of their entire device ecosystem. + +- **Firmware Management**: The platform enables operators to control firmware distribution and updates with sophisticated canary deployment strategies. This includes percentage-based rollouts, device cohort targeting, and manual rollback procedures based on device analytics to minimize risk during firmware updates while ensuring rapid deployment of security patches and feature enhancements. Rollback procedures are not automatic and are always manual go/no-go decisions based on device analytics. + +- **Telemetry Services**: XConf manages comprehensive telemetry profiles and data collection policies, allowing operators to configure what data is collected, how frequently it's gathered, and where it's uploaded. This enables data-driven insights into device performance and user behavior patterns while maintaining privacy compliance and optimizing bandwidth usage. + +- **Device Control Manager (DCM)**: The DCM component handles critical device control settings and log upload policies, providing granular control over device behavior, log collection schedules, and diagnostic data management. This ensures proper device operation and facilitates troubleshooting when issues arise in production environments. + +- **Feature Management (RFC)**: Through the RDK Feature Control system, operators can control feature flags and rules with priority-based evaluation, enabling safe feature rollouts and A/B testing scenarios. Features can be activated for specific device cohorts or gradually rolled out using percentage-based distribution with real-time monitoring and manual rollback capabilities based on device analytics. + +- **Authentication and Authorization**: Robust security mechanisms provide JWT-based authentication with comprehensive role-based access control, ensuring that only authorized personnel can modify configurations. All changes are properly audited and tracked, maintaining complete operational transparency and compliance requirements. + +- **RESTful APIs**: The system exposes comprehensive RESTful APIs for all operations, enabling programmatic access and integration with existing operational tools and workflows. This API-first approach supports automation and custom tooling development while maintaining consistent interface standards across all components. + +- **Metrics and Monitoring**: Built-in observability capabilities include Prometheus metrics collection and OpenTelemetry distributed tracing support, providing complete visibility into system performance and operational health across all components. This enables proactive monitoring and rapid issue resolution. + +- **High Availability**: The platform achieves operational resilience through distributed locking mechanisms and robust data persistence strategies that enable scalable operations across multiple data centers while maintaining data consistency and system reliability with optimized response times. + +## System Architecture + +The XConf system follows a three-tier architecture with clear separation of responsibilities: + +```mermaid +graph TB + subgraph "Client Layer" + RDK[RDK Devices
Config Requests] + WebUI[Web UI
User Interface] + ExtAPI[External APIs
Admin Operations] + end + + subgraph "Service Layer" + WebConfig[XConf WebConfig
Port: 9000
Device API] + UIServer[XConf UI Server
Port: 8081
Web Interface] + Admin[XConf Admin
Port: 9001
Management API] + end + + subgraph "Data Layer" + Cassandra[(Cassandra DB
Primary Storage)] + end + + subgraph "External Services" + SAT[SAT Service
Auth Tokens] + IDP[Identity Provider
User Auth] + Prometheus[Prometheus
Metrics] + OTEL[OTEL Collector
Tracing] + end + + %% Client to Service connections + RDK -->|Configuration Queries| WebConfig + WebUI -->|User Interface| UIServer + ExtAPI -->|Admin Operations| Admin + + %% Service to Service connections + UIServer -->|Proxy Requests| Admin + + %% Service to Data connections + WebConfig --> Cassandra + Admin --> Cassandra + + %% Service to External connections + WebConfig --> SAT + Admin --> SAT + Admin --> IDP + WebConfig --> Prometheus + Admin --> Prometheus + WebConfig --> OTEL + Admin --> OTEL + + %% Styling for better contrast on white background + classDef clientLayer fill:#e1f5fe,stroke:#01579b,stroke-width:2px,color:#000 + classDef serviceLayer fill:#f3e5f5,stroke:#4a148c,stroke-width:2px,color:#000 + classDef dataLayer fill:#e8f5e8,stroke:#1b5e20,stroke-width:2px,color:#000 + classDef externalLayer fill:#fff3e0,stroke:#e65100,stroke-width:2px,color:#000 + + class RDK,WebUI,ExtAPI clientLayer + class WebConfig,UIServer,Admin serviceLayer + class Cassandra dataLayer + class SAT,IDP,Prometheus,OTEL externalLayer +``` + +### Architecture Principles +- **Microservices Design**: Each component has a specific responsibility +- **Stateless Services**: All services are stateless for horizontal scalability +- **Event-Driven**: Asynchronous processing for configuration changes +- **Security First**: Multiple layers of authentication and authorization +- **Observability**: Built-in metrics, logging, and distributed tracing + +## Core Components + +### 1. XConf Admin +**Purpose**: Administrative backend service for configuration management + +**Key Capabilities**: +- Configuration CRUD operations (firmware, DCM, telemetry, RFC) +- Rule-based configuration management with priority handling +- User authentication and authorization +- Change management and audit logging +- API gateway for administrative functions + +**Main Modules**: +- `adminapi/`: REST API handlers and routing +- `auth/`: Authentication and authorization services +- `firmware/`: Firmware configuration management +- `dcm/`: Device Control Manager settings +- `telemetry/`: Telemetry profile management +- `rfc/`: RDK Feature Control management +- `queries/`: Query and reporting services + +### 2. XConf WebConfig +**Purpose**: Data service for RDK devices to retrieve configurations + +**Key Capabilities**: +- High-performance configuration delivery to RDK devices +- Rule engine for dynamic configuration evaluation +- Firmware version determination and distribution control +- Telemetry and DCM settings delivery +- Health checks and diagnostics + +**Main Modules**: +- `dataapi/`: Device-facing API endpoints +- `rulesengine/`: Configuration rule evaluation +- `db/`: Database abstraction and caching +- `security/`: Request validation and security +- `tracing/`: Distributed tracing implementation + +### 3. XConf UI +**Purpose**: Web-based user interface for system administration + +**Key Capabilities**: +- Interactive web interface for configuration management +- Proxy service to XConf Admin backend +- Static asset serving (HTML, CSS, JavaScript) +- User session management + +**Main Modules**: +- `app/`: Angular-based web application +- `server/`: Go-based proxy server +- `templates/`: HTML templates + +## Process Flow Diagrams + +### Device Configuration Request Flow + +```mermaid +sequenceDiagram + participant RDK as RDK Device + participant WC as XConf WebConfig + participant DB as Database + + RDK->>WC: GET /xconf/swu/stb?eStbMac=...&model=... + + WC->>DB: Query config rules + DB-->>WC: Rules & settings + + Note over WC: Evaluate rules
Apply security
Generate JSON + + WC-->>RDK: Configuration Response + + Note over RDK,WC: Response includes firmware version,
download URL, DCM settings, etc.
Device parameters include MAC address,
model, environment, etc. +``` + +### Administrative Configuration Update Flow + +```mermaid +sequenceDiagram + participant Admin as Administrator + participant UI as XConf UI + participant API as XConf Admin + participant DB as Database + + Admin->>UI: Update firmware rule + UI->>API: POST /xconfAdminService/firmwarerule + + Note over API: Validate auth & rule + + API->>DB: Store updated rule + + API-->>UI: Confirmation response + UI-->>Admin: Success notification + + Note over Admin,API: Updated configuration is immediately
available for next device requests +``` + +### Feature Flag Management Flow + +```mermaid +sequenceDiagram + participant Admin as Administrator + participant API as XConf Admin + participant RDK as RDK Device + participant WC as XConf WebConfig + + Admin->>API: Create RFC feature rule + + Note over API: Validate rule conditions
& set priority + + RDK->>WC: Request feature settings + + Note over WC: Evaluate RFC rules by priority
Apply percentage-based rollout + + WC-->>RDK: Feature configuration + + Note over RDK: Apply settings based on config + + Note over Admin,RDK: Flow Summary:
1. Administrator creates RFC feature rules with conditions and rollout percentages
2. RDK devices periodically request feature settings from XConf WebConfig
3. WebConfig evaluates rules by priority and applies percentage-based distribution
4. Devices receive feature configuration and apply settings accordingly +``` + +## Use Cases + +The XConf platform supports diverse operational scenarios across different organizational roles and responsibilities. Each use case demonstrates the platform's capability to address specific configuration management challenges in RDK device deployments. + +### Use Case 1: Firmware Management +**Primary Actors**: Operations Team, DevOps Team +**Supporting Systems**: XConf Admin, XConf WebConfig, Device Fleet + +**Scenario**: Operations teams need to roll out new firmware versions to thousands of RDK devices while minimizing risk and ensuring system stability during the deployment process. + +**Process Flow**: +1. **Upload Firmware Configuration**: Operations team uploads firmware version metadata including download URLs, checksums, and compatibility information through XConf Admin interface +2. **Create Deployment Rules**: Define targeting rules based on device models, environments, and partner configurations with conditional logic +3. **Configure Canary Strategy**: Implement percentage-based rollout starting with 1% of devices, gradually increasing to full deployment +4. **Monitor Deployment Progress**: Track firmware adoption rates, device health metrics, and rollback triggers through real-time dashboards +5. **Emergency Response**: Execute manual rollback procedures based on device analytics if issues are detected during deployment + +**Expected Outcomes**: Controlled firmware distribution with minimized risk, comprehensive deployment visibility, and rapid issue resolution capabilities. + +### Use Case 2: Device Control Manager (DCM) Configuration +**Primary Actors**: Support Team, Operations Team +**Supporting Systems**: XConf Admin, Device Diagnostic Systems + +**Scenario**: Support teams require granular control over device log collection, diagnostic data uploads, and device behavior parameters to facilitate troubleshooting and maintain operational visibility. + +**Process Flow**: +1. **Define Log Upload Policies**: Configure log collection schedules, retention policies, and upload destinations based on device types and support requirements +2. **Configure Device Settings**: Set device behavior parameters including reboot schedules, diagnostic intervals, and maintenance windows +3. **Create Conditional Formulas**: Implement rule-based logic for dynamic device control based on device health, network conditions, and operational requirements +4. **Deploy Settings**: Push DCM configurations to targeted device populations with validation and manual rollback capabilities based on device analytics +5. **Monitor Collection**: Track log upload success rates, diagnostic data quality, and device compliance with configured policies + +**Expected Outcomes**: Automated log collection, improved troubleshooting capabilities, and enhanced device operational visibility. + +### Use Case 3: Feature Flag Control (RFC) +**Primary Actors**: Product Team, QA Team +**Supporting Systems**: XConf Admin, XConf WebConfig, Feature Management System + +**Scenario**: Product teams need to implement safe feature rollouts, conduct A/B testing, and manage experimental features across device populations with precise targeting and manual rollback capabilities based on device analytics. + +**Process Flow**: +1. **Create Feature Control Rules**: Define feature activation conditions based on device characteristics, user segments, and deployment criteria +2. **Configure Rollout Strategy**: Implement percentage-based feature distribution with gradual increase and statistical validation +3. **Set Feature Parameters**: Configure feature-specific settings, default values, and behavioral parameters for targeted device groups +4. **Monitor Feature Performance**: Track feature adoption rates, user engagement metrics, and system performance impact +5. **Optimize and Scale**: Adjust feature parameters based on performance data and scale successful features to broader device populations + +**Expected Outcomes**: Safe feature experimentation, data-driven feature decisions, and controlled feature deployment with rapid iteration capabilities. + +### Use Case 4: Telemetry Management +**Primary Actors**: Analytics Team, Product Team +**Supporting Systems**: XConf Admin, Data Collection Infrastructure, Analytics Platform + +**Scenario**: Analytics teams require comprehensive telemetry data collection from device populations to support product insights, performance optimization, and business intelligence initiatives. + +**Process Flow**: +1. **Define Collection Profiles**: Configure telemetry metrics, collection intervals, and data schemas based on analytical requirements +2. **Target Device Segments**: Create targeting rules for different device populations, user segments, and geographical regions +3. **Configure Upload Schedules**: Set data upload frequencies, bandwidth optimization, and privacy compliance parameters +4. **Validate Data Quality**: Implement data validation rules, quality checks, and error handling procedures +5. **Generate Analytics Reports**: Process collected telemetry data for business insights, performance optimization, and product development + +**Expected Outcomes**: Comprehensive device insights, data-driven product decisions, and optimized user experience based on telemetry analytics. + +### Use Case 5: Environment Configuration Management +**Primary Actors**: DevOps Team, Infrastructure Team +**Supporting Systems**: XConf Admin, CI/CD Pipeline, Environment Management Tools + +**Scenario**: DevOps teams need to maintain configuration consistency across development, staging, and production environments while enabling seamless configuration promotion and environment-specific customizations. + +**Process Flow**: +1. **Define Environment Rules**: Create environment-specific configuration rules with inheritance patterns and override capabilities +2. **Configure Version Management**: Implement configuration versioning with promotion workflows and manual rollback procedures based on device analytics +3. **Enforce Policy Compliance**: Set automated policy validation, compliance checks, and approval workflows for configuration changes +4. **Promote Configurations**: Execute seamless configuration promotion from development through staging to production environments +5. **Monitor Configuration Drift**: Track configuration differences across environments and implement drift detection and correction + +**Expected Outcomes**: Consistent multi-environment configuration management, streamlined deployment workflows, and reduced configuration-related issues. + +### Use Case 6: Real-time Device Configuration +**Primary Actors**: RDK Devices, Automated Systems +**Supporting Systems**: XConf WebConfig, Device Management Platform, Network Infrastructure + +**Scenario**: RDK devices automatically request and receive configuration updates, apply settings based on their characteristics, and report status back to the platform for monitoring and compliance verification. + +**Process Flow**: +1. **Request Configurations**: Devices periodically query XConf WebConfig for current configuration updates based on device parameters +2. **Receive Targeted Settings**: Platform delivers device-specific configurations including firmware versions, feature settings, and operational parameters +3. **Apply Configuration Changes**: Devices validate and apply received configurations with appropriate error handling and manual rollback capabilities based on operator decisions +4. **Report Status Updates**: Devices provide feedback on configuration application success, system health, and operational status +5. **Maintain Compliance**: Continuous monitoring ensures devices maintain compliance with current configuration policies + +**Expected Outcomes**: Automated device configuration management, real-time compliance monitoring, and seamless configuration distribution across device populations. + +### Use Case 7: System Monitoring and Observability +**Primary Actors**: Operations Team, Support Team, DevOps Team +**Supporting Systems**: Prometheus, OTEL Collector, Monitoring Dashboards, Alert Management + +**Scenario**: Cross-functional teams require comprehensive monitoring of system health, deployment progress, performance metrics, and operational status through integrated dashboards and proactive alerting mechanisms. + +**Process Flow**: +1. **Configure Monitoring Infrastructure**: Set up comprehensive metrics collection, distributed tracing, and log aggregation across all system components +2. **Create Performance Dashboards**: Implement real-time dashboards showing system health, device connectivity, and configuration distribution metrics +3. **Define Alert Policies**: Configure intelligent alerting for system anomalies, performance degradation, and operational issues +4. **Track Deployment Progress**: Monitor configuration rollouts, feature adoption rates, and deployment success metrics +5. **Investigate and Resolve Issues**: Use integrated monitoring data for rapid issue identification, root cause analysis, and resolution tracking + +**Expected Outcomes**: Proactive system monitoring, rapid issue detection and resolution, and comprehensive operational visibility across the entire XConf platform. + +## API Overview + +### XConf Admin API (`/xconfAdminService`) +**Authentication**: JWT tokens or session-based authentication +**Base URL**: `http://host:9001/xconfAdminService` + +**Key Endpoints**: +- `GET/POST/PUT/DELETE /firmwareconfig` - Firmware configuration management +- `GET/POST/PUT/DELETE /firmwarerule` - Firmware rule management +- `GET/POST/PUT/DELETE /dcm/formula` - DCM formula management +- `GET/POST/PUT/DELETE /telemetry/profile` - Telemetry profile management +- `GET/POST/PUT/DELETE /rfc/feature` - Feature rule management +- `GET /queries/environments` - Environment queries +- `POST /auth/basic` - Basic authentication +- `GET /provider` - Authentication provider info + +### XConf WebConfig API (`/xconf`) +**Authentication**: Device-based validation +**Base URL**: `http://host:9000/xconf` + +**Key Endpoints**: +- `GET /swu/stb` - Firmware configuration for STB devices +- `GET /loguploader/getSettings` - Log upload settings +- `GET /rfc/feature/getSettings` - Feature settings +- `GET /telemetry/getTelemetryProfiles` - Telemetry profiles +- `GET /dcm/getSettings` - DCM settings + +### Request/Response Examples + +**Device Firmware Request**: +```bash +GET /xconf/swu/stb?eStbMac=AA:BB:CC:DD:EE:FF&model=MODEL_X&env=PROD +``` + +**Firmware Response**: +```json +{ + "firmwareVersion": "2.1.0", + "firmwareDownloadURL": "https://firmware.example.com/firmware-2.1.0.bin", + "firmwareFilename": "firmware-2.1.0.bin", + "rebootImmediately": false, + "forceHttp": false +} +``` + +## Configuration Management + +XConf utilizes HOCON (Human-Optimized Config Object Notation) configuration files that provide comprehensive control over all system components. The platform supports three distinct configuration profiles optimized for different operational responsibilities. + +### Configuration Architecture + +```mermaid +graph TB + subgraph "Configuration Sources" + AdminConf[XConf Admin Config
xconfadmin.conf] + WebConfigConf[XConf WebConfig Config
xconfwebconfig.conf] + UIConf[XConf UI Config
xconfui.conf] + end + + subgraph "Configuration Categories" + ServerConfig[Server Configuration
• Port bindings
• Timeouts
• Metrics] + ServiceConfig[Service Integration
• SAT Authentication
• External APIs
• Feature toggles] + DataConfig[Data Layer
• Cassandra clusters
• Cache settings
• Connection pools] + SecurityConfig[Security Settings
• JWT tokens
• TLS certificates
• Authentication] + end + + subgraph "Runtime Environment" + EnvVars[Environment Variables
• SAT_CLIENT_ID
• DATABASE_PASSWORD
• SECURITY_TOKEN_KEY] + Deployment[Deployment Context
• Development
• Staging
• Production] + end + + AdminConf --> ServerConfig + AdminConf --> ServiceConfig + AdminConf --> DataConfig + AdminConf --> SecurityConfig + + WebConfigConf --> ServerConfig + WebConfigConf --> ServiceConfig + WebConfigConf --> DataConfig + + UIConf --> ServerConfig + UIConf --> ServiceConfig + + EnvVars --> ServiceConfig + EnvVars --> SecurityConfig + Deployment --> ServiceConfig + + %% Styling + classDef configSource fill:#e3f2fd,stroke:#0277bd,stroke-width:2px,color:#000 + classDef configCategory fill:#f3e5f5,stroke:#6a1b9a,stroke-width:2px,color:#000 + classDef runtime fill:#e8f5e8,stroke:#2e7d32,stroke-width:2px,color:#000 + + class AdminConf,WebConfigConf,UIConf configSource + class ServerConfig,ServiceConfig,DataConfig,SecurityConfig configCategory + class EnvVars,Deployment runtime +``` + +### XConf Admin Configuration + +**Primary Responsibilities**: Administrative backend operations, user authentication, and configuration management workflows. + +**Key Configuration Areas**: +- **Service Integration**: Comprehensive external service connections including SAT authentication, Identity Provider (IDP), device services, account management, and tagging systems +- **Canary Management**: Advanced deployment controls with timezone support, percentage-based rollouts, and partner-specific configurations +- **Authentication Framework**: JWT-based security with configurable token validation and role-based access control +- **Cache Strategy**: Multi-level caching with configurable refresh cycles, distributed locking mechanisms, and performance optimization +- **Database Operations**: Cassandra cluster management with SSL support, connection pooling, and query optimization settings +- **Tracing & Observability**: OpenTelemetry integration with configurable endpoints and distributed tracing capabilities + +**Notable Features**: +- Supports 20+ external service integrations with individual timeout and retry configurations +- Configurable canary deployment windows with timezone awareness +- Advanced distributed locking for concurrent operations +- Comprehensive audit logging and security token management + +### XConf WebConfig Configuration + +**Primary Responsibilities**: High-performance device-facing API operations and configuration delivery optimization. + +**Key Configuration Areas**: +- **Performance Optimization**: Enhanced caching strategies with group service integration, cache expiration policies, and connection pooling +- **Device Integration**: Specialized device service connections with model-specific configurations and validation rules +- **Feature Toggles**: Granular control over RFC features, firmware penetration metrics, and experimental capabilities +- **Security Enhancements**: Device-specific authentication, token management for firmware delivery, and protocol-based security controls +- **Data Processing**: Advanced configuration preprocessing, IP address parsing, and network mask management +- **Metrics Collection**: Device interaction metrics, model-based request tracking, and performance monitoring + +**Notable Features**: +- Device-optimized caching with 4-hour refresh cycles for group services +- Security token integration for firmware download protection +- Advanced IP address processing with IPv4/IPv6 network mask support +- RFC precooking capabilities for improved response times +- Model-specific feature enablement for targeted device populations + +### XConf UI Configuration + +**Primary Responsibilities**: Web-based administration interface and proxy service management. + +**Key Configuration Areas**: +- **Proxy Architecture**: Streamlined configuration for backend service integration through XConf Admin API +- **Web Server Settings**: Port configuration, static asset management, and web root directory specification +- **Logging Framework**: Structured logging with file-based output and caller information tracking +- **Development Support**: Simplified configuration for development environments and debugging capabilities + +**Notable Features**: +- Lightweight configuration focused on web interface requirements +- Automatic proxy routing to XConf Admin backend services +- Development-friendly logging with detailed caller information +- Minimal external dependencies for rapid deployment + +### Configuration Management Framework + +**Environment Variable Integration**: The platform leverages secure environment variable injection for sensitive configuration parameters including SAT_CLIENT_ID and SAT_CLIENT_SECRET for service-to-service authentication credentials, DATABASE_USER and DATABASE_PASSWORD for Cassandra database authentication, and SECURITY_TOKEN_KEY for JWT token signing and validation operations. + +**Configuration Validation & Processing**: XConf implements comprehensive HOCON format validation with nested object support, automatic environment variable substitution with intelligent default fallbacks, proactive service dependency validation and health checking mechanisms, and real-time configuration drift detection with automated alerting capabilities to ensure operational consistency. + +**Multi-Environment Deployment Patterns**: The system supports distinct deployment configurations optimized for different operational contexts. Development environments utilize local configuration profiles with disabled external services and enhanced debug logging for rapid development cycles. Staging environments implement production-like configurations with dedicated test service endpoints and comprehensive monitoring integration for pre-production validation. Production deployments feature full external service integration with performance-optimized settings and enterprise-grade security hardening measures. + +**Advanced Rule Engine & Logic**: XConf's configuration engine supports sophisticated conditional configuration mechanisms using complex boolean expressions for environment-specific settings, priority-based evaluation systems with hierarchical configuration override capabilities, temporal controls enabling time-based configuration activation and automated feature scheduling, and percentage distribution algorithms providing gradual rollout capabilities with statistical distribution controls for safe deployment practices. + +**Comprehensive Configuration Scope**: The platform manages diverse configuration types including firmware management systems for version control and deployment strategies, DCM policies governing log collection schedules and device behavior parameters, RFC features enabling feature flag management and A/B testing configurations, telemetry profiles defining data collection policies and analytics configurations, and security policies establishing authentication requirements and access control matrices across all system components. + +## Deployment Architecture + +XConf's production deployment architecture follows enterprise-grade patterns with multiple layers of redundancy, horizontal scaling capabilities, and comprehensive observability integration. The platform is designed to handle high-throughput device communication while maintaining configuration consistency and operational reliability across distributed environments. + +### Recommended Deployment Pattern + +```mermaid +graph TB + subgraph "Load Balancer Layer" + LB[Load Balancer
NGINX/HAProxy] + end + + subgraph "Service Instances" + XA1[XConf Admin
Instance 1] + XA2[XConf Admin
Instance 2] + WC1[XConf WebConfig
Instance 1] + WC2[XConf WebConfig
Instance 2] + UI1[XConf UI
Instance 1] + UI2[XConf UI
Instance 2] + end + + subgraph "Data Layer" + C1[(Cassandra
Node 1)] + C2[(Cassandra
Node 2)] + C3[(Cassandra
Node 3)] + end + + subgraph "External Services" + SAT[SAT Service] + IDP[Identity Provider] + Prometheus[Prometheus] + OTEL[OTEL Collector] + end + + LB --> XA1 + LB --> XA2 + LB --> WC1 + LB --> WC2 + LB --> UI1 + LB --> UI2 + + XA1 --> C1 + XA2 --> C2 + WC1 --> C1 + WC2 --> C3 + + XA1 --> SAT + XA2 --> SAT + WC1 --> SAT + WC2 --> SAT +``` + +The deployment architecture implements a layered approach where the load balancer efficiently distributes incoming traffic across multiple service instances based on request type and current system load. Each service type operates multiple instances to ensure high availability and fault tolerance, with automatic failover mechanisms protecting against individual service failures. The Cassandra cluster provides distributed data storage with automatic replication and sharding capabilities, ensuring data consistency and availability even during node failures. External services integration encompasses authentication systems for secure access control, comprehensive monitoring infrastructure for operational visibility, and distributed tracing capabilities for performance optimization and troubleshooting support. + +### Infrastructure Requirements +- **Compute**: Minimum 2 CPU cores, 4GB RAM per service instance +- **Storage**: SSD storage for database with replication +- **Network**: High-bandwidth connection for firmware distribution +- **Database**: Cassandra cluster with minimum 3 nodes for HA + +### Scaling Considerations +- **Horizontal Scaling**: Stateless services support easy horizontal scaling +- **Database Sharding**: Cassandra provides automatic sharding and replication +- **Load Distribution**: Geographic distribution for global deployments + +## Security Model + +### Authentication Layers +1. **Service-to-Service**: SAT (Security Access Token) based authentication +2. **User Authentication**: Integration with enterprise identity providers +3. **Device Authentication**: MAC address and certificate-based validation +4. **API Security**: JWT tokens with role-based access control + +### Authorization Framework +- **Entity-Based Permissions**: Granular permissions per configuration entity +- **Role-Based Access Control**: Predefined roles with specific capabilities +- **Operation-Level Security**: Read/write permissions per API endpoint +- **Environment Isolation**: Strict separation between environments + +### Security Features +- **Token Validation**: Comprehensive JWT token validation and refresh +- **Request Sanitization**: Input validation and sanitization +- **Audit Logging**: Complete audit trail for all configuration changes +- **Secure Communication**: HTTPS/TLS for all service communications + +## Getting Started + +### Prerequisites +- **Go 1.23+**: For building and running the services +- **Cassandra 3.11+**: For data persistence +- **Node.js 24.1.0+**: For UI development +- **Git**: For source code management + +### Quick Start + +1. **Clone Repositories**: +```bash +git clone https://github.com/rdkcentral/xconfadmin.git +git clone https://github.com/rdkcentral/xconfui.git +git clone https://github.com/rdkcentral/xconfwebconfig.git +``` + +2. **Start Database**: +```bash +# Start Cassandra and create schema +cassandra -f & +cqlsh -f xconfwebconfig-main/db/db_init.cql +``` + +3. **Configure Services**: +```bash +# Copy and modify configuration files +cp xconfadmin/config/sample_xconfadmin.conf /etc/xconf/xconfadmin.conf +cp xconfwebconfig-main/config/sample_xconfwebconfig.conf /etc/xconf/xconfwebconfig.conf +cp xconfui-main/config/sample_xconfui.conf /etc/xconf/xconfui.conf +``` + +4. **Build and Run Services**: +```bash +# Build XConf Admin +cd xconfadmin && make build +./bin/xconfadmin-linux-amd64 -f /etc/xconf/xconfadmin.conf & + +# Build XConf WebConfig +cd xconfwebconfig-main && make build +./bin/xconfwebconfig-linux-amd64 -f /etc/xconf/xconfwebconfig.conf & + +# Build and Run XConf UI +cd xconfui-main +npm install && grunt install +go run *.go -f /etc/xconf/xconfui.conf & +``` + +5. **Access the System**: +- **Admin UI**: http://localhost:8081 +- **Admin API**: http://localhost:9001/xconfAdminService +- **WebConfig API**: http://localhost:9000/xconf + +### Configuration Tips +- Set environment variables for SAT_CLIENT_ID, SAT_CLIENT_SECRET, and SECURITY_TOKEN_KEY +- Configure appropriate log levels for production deployments +- Enable metrics and tracing for production monitoring +- Use environment-specific configuration files +- Implement proper backup strategies for Cassandra + +### Development Workflow +1. Make changes to source code +2. Run unit tests: `go test ./...` +3. Build and test locally +4. Deploy to staging environment +5. Run integration tests +6. Deploy to production with canary rollout + + +This overview provides a comprehensive understanding of the XConf system architecture, components, and operational patterns. For detailed API documentation, refer to the individual API documentation files in each component directory. From cccc8527f5270d538310b64e3bfb7079a993befd Mon Sep 17 00:00:00 2001 From: LakshmipriyaPurushan <60867402+LakshmipriyaPurushan@users.noreply.github.com> Date: Mon, 19 Jan 2026 21:59:54 +0530 Subject: [PATCH 09/23] Update overview2.md --- docs/overview2.md | 3 ++- 1 file changed, 2 insertions(+), 1 deletion(-) diff --git a/docs/overview2.md b/docs/overview2.md index af0fe58..eb32eb8 100644 --- a/docs/overview2.md +++ b/docs/overview2.md @@ -20,7 +20,7 @@ XConf is a comprehensive configuration management platform designed for RDK (Ref - **Centralized Configuration Management**: XConf serves as a single point of control for all device configurations across large-scale RDK deployments. This unified approach eliminates configuration fragmentation and ensures consistency across thousands of devices in the field, providing operators with a comprehensive view of their entire device ecosystem. -- **Firmware Management**: The platform enables operators to control firmware distribution and updates with sophisticated canary deployment strategies. This includes percentage-based rollouts, device cohort targeting, and manual rollback procedures based on device analytics to minimize risk during firmware updates while ensuring rapid deployment of security patches and feature enhancements. Rollback procedures are not automatic and are always manual go/no-go decisions based on device analytics. +- **Firmware Management**: The platform enables operators to control firmware distribution and updates with sophisticated canary deployment strategies. This includes percentage-based rollouts, device cohort targeting, and manual rollback procedures based on device analytics to minimize risk during firmware updates while ensuring rapid deployment of security patches and feature enhancements. - **Telemetry Services**: XConf manages comprehensive telemetry profiles and data collection policies, allowing operators to configure what data is collected, how frequently it's gathered, and where it's uploaded. This enables data-driven insights into device performance and user behavior patterns while maintaining privacy compliance and optimizing bandwidth usage. @@ -651,3 +651,4 @@ go run *.go -f /etc/xconf/xconfui.conf & This overview provides a comprehensive understanding of the XConf system architecture, components, and operational patterns. For detailed API documentation, refer to the individual API documentation files in each component directory. + From 49bdb7fafe36860bc4431a3a66f7297538178d18 Mon Sep 17 00:00:00 2001 From: LakshmipriyaPurushan <60867402+LakshmipriyaPurushan@users.noreply.github.com> Date: Tue, 20 Jan 2026 11:54:21 +0530 Subject: [PATCH 10/23] Add files via upload --- docs/tagging_service_API_documentation_new.md | 818 ++++++++++++++++++ 1 file changed, 818 insertions(+) create mode 100644 docs/tagging_service_API_documentation_new.md diff --git a/docs/tagging_service_API_documentation_new.md b/docs/tagging_service_API_documentation_new.md new file mode 100644 index 0000000..e1cac42 --- /dev/null +++ b/docs/tagging_service_API_documentation_new.md @@ -0,0 +1,818 @@ +# XConf Tagging Service API Documentation + +**Version:** 1.0 +**Last Updated:** January 2026 +**Base URL:** `/taggingService` +**Default Port:** 9001 + +--- + +## Table of Contents + +1. [Overview](#overview) +2. [Authentication](#authentication) +3. [Core Concepts](#core-concepts) +4. [API Endpoints](#api-endpoints) +5. [Data Models](#data-models) +6. [Request/Response Examples](#requestresponse-examples) +7. [Error Handling](#error-handling) +8. [Usage Patterns](#usage-patterns) +9. [Best Practices](#best-practices) + +--- + +## Overview + +The XConf Tagging Service API provides comprehensive tag management capabilities for device grouping and configuration targeting. It enables dynamic device categorization through tag-based systems, supporting both individual member management and percentage-based distribution for advanced deployment strategies. + +### Key Capabilities + +- **Tag Management**: Create, read, update, and delete device tags +- **Member Management**: Add/remove individual or batch members to/from tags +- **Tag Queries**: Retrieve tags by ID, list all tags, find tags containing specific members +- **Percentage-Based Distribution**: Calculate deterministic percentage values for devices to enable percentage-based rollouts +- **Batch Operations**: Efficiently manage large numbers of devices in single API calls +- **Real-time Updates**: Immediate availability of tag changes across all services + +### Service Architecture + +The Tagging Service operates independently and provides direct tag management without intermediate caching layers, ensuring immediate consistency across the XConf platform. + +--- + +## Authentication + +All endpoints require authentication via JWT token or session-based authentication. + +### Authentication Header Format + +``` +Authorization: Bearer +``` + +### Authentication Requirements + +- **JWT Tokens**: Must be valid and non-expired +- **Session-based**: Valid session credentials required +- **Role-based Access Control**: Operations require appropriate permissions +- **Service-to-Service**: SAT (Security Access Token) for inter-service communication + +--- + +## Core Concepts + +### Tags + +A tag is a named grouping mechanism for devices. Tags can contain multiple device members and are identified by a unique string identifier. + +**Tag Characteristics:** +- Unique identifier (string) +- List of member identifiers (device addresses, IDs, etc.) +- Last updated timestamp +- No size limitations (though practical limits apply) + +### Members + +Members are individual devices identified by: +- MAC addresses (e.g., `AA:BB:CC:DD:EE:FF`) +- Device IDs (e.g., `device_12345`) +- Account IDs (e.g., `account_67890`) +- Any custom string identifier + +### Percentage Distribution + +Percentage values are calculated deterministically using SipHash algorithm, enabling consistent percentage-based device selection for: +- Canary deployments +- A/B testing +- Gradual rollouts +- Statistical device sampling + +--- + +## API Endpoints + +### 1. Get All Tags + +Retrieve all available tags in the system with optional full object expansion. + +**Request:** +``` +GET /taggingService/tags +GET /taggingService/tags?full +``` + +**Query Parameters:** + +| Parameter | Type | Required | Description | +|-----------|------|----------|-------------| +| `full` | flag | No | Returns complete tag objects with members instead of just tag IDs | + +**Response (without `full`):** +```json +[ + "production_devices", + "beta_testers", + "development_units", + "canary_group_1" +] +``` + +**Response (with `full`):** +```json +[ + { + "id": "production_devices", + "members": [ + "AA:BB:CC:DD:EE:01", + "AA:BB:CC:DD:EE:02", + "AA:BB:CC:DD:EE:03" + ], + "updated": 1699875600000 + }, + { + "id": "beta_testers", + "members": [ + "AA:BB:CC:DD:EE:10", + "AA:BB:CC:DD:EE:11" + ], + "updated": 1699875500000 + } +] +``` + +**HTTP Status Codes:** +- `200 OK`: Successfully retrieved tags +- `500 Internal Server Error`: Server-side processing error + +--- + +### 2. Get Tag by ID + +Retrieve a specific tag with complete information including all members and metadata. + +**Request:** +``` +GET /taggingService/tags/{tag} +``` + +**Parameters:** + +| Parameter | Type | Location | Required | Description | +|-----------|------|----------|----------|-------------| +| `tag` | string | Path | Yes | Tag identifier | + +**Response:** +```json +{ + "id": "production_devices", + "members": [ + "AA:BB:CC:DD:EE:01", + "AA:BB:CC:DD:EE:02", + "AA:BB:CC:DD:EE:03", + "AA:BB:CC:DD:EE:04" + ], + "updated": 1699875600000 +} +``` + +**HTTP Status Codes:** +- `200 OK`: Tag found and returned +- `400 Bad Request`: Invalid tag parameter +- `404 Not Found`: Tag does not exist +- `500 Internal Server Error`: Server processing error + +--- + +### 3. Delete Tag + +Delete a specific tag from the system completely. + +**Request:** +``` +DELETE /taggingService/tags/{tag} +``` + +**Parameters:** + +| Parameter | Type | Location | Required | Description | +|-----------|------|----------|----------|-------------| +| `tag` | string | Path | Yes | Tag identifier to delete | + +**Response:** +- No response body on successful deletion (HTTP 204) + +**HTTP Status Codes:** +- `204 No Content`: Tag successfully deleted +- `400 Bad Request`: Invalid tag parameter +- `404 Not Found`: Tag not found +- `500 Internal Server Error`: Server processing error + +--- + +### 4. Add Members to Tag + +Add multiple members to an existing tag in a batch operation. + +**Request:** +``` +PUT /taggingService/tags/{tag}/members +Content-Type: application/json + +[ + "AA:BB:CC:DD:EE:05", + "AA:BB:CC:DD:EE:06", + "device_id_12345" +] +``` + +**Parameters:** + +| Parameter | Type | Location | Required | Description | +|-----------|------|----------|----------|-------------| +| `tag` | string | Path | Yes | Tag identifier | +| Body | array | Request Body | Yes | Array of member identifiers (max 1000) | + +**Constraints:** +- Maximum 1000 members per request +- Exceeding limit returns 400 Bad Request +- Empty member list returns 400 Bad Request + +**Response:** +- Success confirmation with no response body (HTTP 200 OK) + +**HTTP Status Codes:** +- `200 OK`: Members successfully added +- `400 Bad Request`: Invalid input, batch size exceeded, or empty member list +- `404 Not Found`: Tag not found +- `500 Internal Server Error`: Server processing error + +--- + +### 5. Remove Single Member from Tag + +Remove a single member from a specific tag. + +**Request:** +``` +DELETE /taggingService/tags/{tag}/members/{member} +``` + +**Parameters:** + +| Parameter | Type | Location | Required | Description | +|-----------|------|----------|----------|-------------| +| `tag` | string | Path | Yes | Tag identifier | +| `member` | string | Path | Yes | Member identifier to remove | + +**Response:** +```json +{ + "id": "production_devices", + "members": [ + "AA:BB:CC:DD:EE:01", + "AA:BB:CC:DD:EE:03", + "AA:BB:CC:DD:EE:04" + ], + "updated": 1699875700000 +} +``` + +**HTTP Status Codes:** +- `200 OK`: Member successfully removed and tag returned +- `204 No Content`: Member successfully removed +- `400 Bad Request`: Invalid parameters +- `404 Not Found`: Tag or member not found +- `500 Internal Server Error`: Server processing error + +--- + +### 6. Remove Multiple Members from Tag + +Remove multiple members from a tag in a single batch operation. + +**Request:** +``` +DELETE /taggingService/tags/{tag}/members +Content-Type: application/json + +[ + "AA:BB:CC:DD:EE:02", + "AA:BB:CC:DD:EE:05", + "device_id_old_123" +] +``` + +**Parameters:** + +| Parameter | Type | Location | Required | Description | +|-----------|------|----------|----------|-------------| +| `tag` | string | Path | Yes | Tag identifier | +| Body | array | Request Body | Yes | Array of member identifiers to remove (max 1000) | + +**Constraints:** +- Maximum 1000 members per request +- Exceeding limit returns 400 Bad Request + +**Response:** +- No response body on successful removal (HTTP 204 No Content) + +**HTTP Status Codes:** +- `204 No Content`: Members successfully removed +- `400 Bad Request`: Invalid input or batch size exceeded +- `404 Not Found`: Tag not found +- `500 Internal Server Error`: Server processing error + +--- + +### 7. Get Tag Members + +Retrieve all members of a specific tag. + +**Request:** +``` +GET /taggingService/tags/{tag}/members +``` + +**Parameters:** + +| Parameter | Type | Location | Required | Description | +|-----------|------|----------|----------|-------------| +| `tag` | string | Path | Yes | Tag identifier | + +**Response:** +```json +[ + "AA:BB:CC:DD:EE:01", + "AA:BB:CC:DD:EE:02", + "AA:BB:CC:DD:EE:03", + "AA:BB:CC:DD:EE:04", + "device_id_12345", + "device_id_67890" +] +``` + +**HTTP Status Codes:** +- `200 OK`: Members successfully retrieved +- `400 Bad Request`: Invalid tag parameter +- `404 Not Found`: Tag not found +- `500 Internal Server Error`: Server processing error + +--- + +### 8. Get Tags by Member + +Retrieve all tags containing a specific member. + +**Request:** +``` +GET /taggingService/tags/members/{member} +``` + +**Parameters:** + +| Parameter | Type | Location | Required | Description | +|-----------|------|----------|----------|-------------| +| `member` | string | Path | Yes | Member identifier to search for | + +**Response:** +```json +[ + { + "id": "production_devices", + "members": [ + "AA:BB:CC:DD:EE:01", + "AA:BB:CC:DD:EE:02", + "other_device_ids..." + ], + "updated": 1699875600000 + }, + { + "id": "priority_group", + "members": [ + "AA:BB:CC:DD:EE:01", + "priority_device_ids..." + ], + "updated": 1699875550000 + } +] +``` + +**HTTP Status Codes:** +- `200 OK`: Tags successfully retrieved +- `400 Bad Request`: Invalid member parameter +- `404 Not Found`: Member not found in any tags +- `500 Internal Server Error`: Server processing error + +--- + +### 9. Calculate Percentage Value for Member + +Calculate deterministic percentage value for a member using SipHash algorithm. + +**Request:** +``` +GET /taggingService/tags/members/{member}/percentages/calculation +``` + +**Parameters:** + +| Parameter | Type | Location | Required | Description | +|-----------|------|----------|----------|-------------| +| `member` | string | Path | Yes | Member identifier for calculation | + +**Algorithm Details:** +- **Name**: SipHash-2-4 +- **Key Configuration**: Fixed keys for consistent results +- **Output Range**: 0-99 (deterministic percentage value) +- **Use Case**: Percentage-based device rollout strategies +- **Deterministic**: Same member always returns same percentage value + +**Response:** +```json +67 +``` + +**HTTP Status Codes:** +- `200 OK`: Percentage calculated successfully +- `400 Bad Request`: Invalid member parameter +- `500 Internal Server Error`: Server processing error + +--- + +## Data Models + +### Tag Object + +```json +{ + "id": "string", // Unique tag identifier (required) + "members": ["string"], // Array of member identifiers + "updated": "integer" // Unix timestamp (milliseconds) of last update +} +``` + +**Field Details:** + +| Field | Type | Required | Description | +|-------|------|----------|-------------| +| `id` | string | Yes | Unique identifier for the tag | +| `members` | array | No | Array of device MAC addresses, device IDs, or identifiers | +| `updated` | integer | No | Unix timestamp in milliseconds of last modification | + +### Member Identifier Formats + +Supported member identifier formats: + +| Format | Example | Description | +|--------|---------|-------------| +| MAC Address | `AA:BB:CC:DD:EE:FF` | 48-bit hardware address in colon-separated hex | +| Device ID | `device_12345` | Alphanumeric device identifier | +| Account ID | `account_67890` | Account or subscription identifier | +| Custom String | `custom_identifier_1` | Any string-based identifier | + +--- + +## Request/Response Examples + +### Example 1: Create and Populate a Canary Tag + +**Step 1: Add devices to canary tag** + +```bash +curl -X PUT "http://localhost:9001/taggingService/tags/canary_group_1/members" \ + -H "Content-Type: application/json" \ + -H "Authorization: Bearer " \ + -d '[ + "AA:BB:CC:DD:EE:01", + "AA:BB:CC:DD:EE:02", + "AA:BB:CC:DD:EE:03" + ]' +``` + +**Step 2: Verify tag members** + +```bash +curl -X GET "http://localhost:9001/taggingService/tags/canary_group_1/members" \ + -H "Authorization: Bearer " +``` + +**Step 3: Calculate percentages for devices** + +```bash +curl -X GET "http://localhost:9001/taggingService/tags/members/AA:BB:CC:DD:EE:01/percentages/calculation" \ + -H "Authorization: Bearer " +``` + +### Example 2: Batch Update Production Devices + +```bash +# Add devices +curl -X PUT "http://localhost:9001/taggingService/tags/production_devices/members" \ + -H "Content-Type: application/json" \ + -H "Authorization: Bearer " \ + -d '[ + "device_prod_001", + "device_prod_002", + "device_prod_003", + "device_prod_004", + "device_prod_005" + ]' + +# Remove outdated device +curl -X DELETE "http://localhost:9001/taggingService/tags/production_devices/members" \ + -H "Content-Type: application/json" \ + -H "Authorization: Bearer " \ + -d '[ + "device_prod_001" + ]' + +# Get all production devices +curl -X GET "http://localhost:9001/taggingService/tags/production_devices/members" \ + -H "Authorization: Bearer " +``` + +### Example 3: Find All Tags for a Device + +```bash +curl -X GET "http://localhost:9001/taggingService/tags/members/device_prod_002" \ + -H "Authorization: Bearer " +``` + +--- + +## Error Handling + +### Common Error Responses + +**400 Bad Request - Missing Tag** +```json +{ + "status": 400, + "message": "tag is not specified" +} +``` + +**400 Bad Request - Empty Member List** +```json +{ + "status": 400, + "message": "member list is empty" +} +``` + +**400 Bad Request - Batch Size Exceeded** +```json +{ + "status": 400, + "message": "batch size 1500 exceeds the limit of 1000" +} +``` + +**404 Not Found** +```json +{ + "status": 404, + "message": "production_devices tag not found" +} +``` + +**500 Internal Server Error** +```json +{ + "status": 500, + "message": "Internal server error occurred while processing the request" +} +``` + +### HTTP Status Code Reference + +| Code | Status | Description | +|------|--------|-------------| +| 200 | OK | Request successful | +| 204 | No Content | Successful deletion/removal | +| 400 | Bad Request | Invalid input, missing parameters, batch size exceeded | +| 401 | Unauthorized | Authentication failed or missing token | +| 404 | Not Found | Resource not found | +| 500 | Internal Server Error | Server-side processing error | + +--- + +## Usage Patterns + +### Pattern 1: Percentage-Based Rollout + +``` +1. Create/identify target tag: "firmware_v2.1_rollout" +2. Add devices to tag in batches of 1000 +3. For each device, calculate percentage value +4. Select devices where percentage < 10 for initial rollout +5. Monitor rollout success +6. Gradually increase percentage threshold (10 → 25 → 50 → 100) +7. Remove tag when rollout complete +``` + +### Pattern 2: A/B Testing Scenarios + +``` +1. Create two tags: "feature_old_version" and "feature_new_version" +2. Add 50% of devices to each tag +3. Use percentage calculation for consistent split +4. Monitor metrics for both groups +5. Compare outcomes +6. Migrate all devices to winning version +7. Remove losing version tag +``` + +### Pattern 3: Device Segmentation by Model + +``` +1. Create model-specific tags: + - "model_x1_devices" + - "model_x2_devices" + - "model_x3_devices" +2. Populate tags during device registration +3. Query tags by device to determine applicable configs +4. Remove devices from old model tags when replaced +``` + +### Pattern 4: Geographic Distribution + +``` +1. Create region-specific tags: + - "region_us_west_devices" + - "region_us_east_devices" + - "region_eu_devices" +2. Assign devices based on registration location +3. Deploy region-specific configurations +4. Monitor regional performance metrics +``` + +--- + +## Best Practices + +### Tag Naming Conventions + +✓ **Do:** +- Use lowercase with underscores: `production_devices`, `beta_testers` +- Include environment prefix: `prod_`, `staging_`, `dev_` +- Use descriptive names: `model_x1_devices`, `region_us_west` +- Keep names concise (max 64 characters recommended) +- Use consistent naming patterns + +✗ **Don't:** +- Use special characters (except underscores) +- Create ambiguous names without context +- Mix naming conventions in same system +- Use names that are too long + +### Member Management + +**Batch Operations:** +- Use batch operations for multiple members +- Maximum 1000 members per request +- Split large operations into multiple requests +- Prefer PUT/DELETE over individual operations + +**Validation:** +- Validate member identifiers before adding +- Ensure consistency in identifier format +- Remove duplicate members before adding +- Check for typos in device IDs + +**Monitoring:** +- Track tag membership changes +- Audit tag modifications +- Monitor tag sizes and growth +- Alert on unexpected changes + +### Performance Considerations + +**Query Optimization:** +- Use `/tags?full` only when needed +- Query specific tags rather than listing all +- Cache tag data locally when appropriate +- Batch read operations + +**Scaling:** +- Split large tags if exceeding 10,000 members +- Use logical tag hierarchies for organization +- Monitor API response times +- Implement client-side caching + +### Security Best Practices + +**Authentication:** +- Always use valid JWT tokens +- Rotate tokens regularly +- Use secure token storage +- Implement token expiration + +**Authorization:** +- Verify user permissions before operations +- Implement least-privilege access +- Audit all tag modifications +- Log sensitive operations + +**Input Validation:** +- Validate all member identifiers +- Sanitize tag names +- Check batch sizes +- Verify request parameters + +--- + +## Rate Limiting and Quotas + +| Resource | Limit | Notes | +|----------|-------|-------| +| Batch Member Operations | 1000 members/request | Split into multiple requests if needed | +| Tag Name Length | 256 characters | Recommended max: 64 characters | +| Member ID Length | 256 characters | Depends on identifier format | +| Concurrent Connections | Per server config | Default: 100 connections | +| API Request Rate | Unlimited | Subject to authentication limits | +| Tag Count | No documented limit | Monitor system performance | +| Members per Tag | No documented limit | Recommend splitting if > 10,000 | + +--- + +## Troubleshooting + +### Common Issues + +**Issue: 404 Tag Not Found** +- Verify tag name spelling and case sensitivity +- Check if tag was recently deleted +- List all available tags: `GET /taggingService/tags` + +**Issue: 400 Batch Size Exceeded** +- Split requests into chunks of max 1000 members +- Use loop to add members in batches +- Validate batch size before sending + +**Issue: 401 Unauthorized** +- Verify JWT token validity and expiration +- Check Authorization header format: `Bearer ` +- Regenerate token if expired + +**Issue: Member Not Found in Percentage Calculation** +- Verify member exists in at least one tag +- Check member identifier format +- Ensure no special character escaping issues + +**Issue: Slow Tag Queries** +- Reduce tag size by splitting into multiple tags +- Use specific tag queries instead of listing all +- Implement client-side caching +- Check network connectivity + +--- + +## API Integration Guide + +### Integration with XConf Admin Service + +**Tag-based Configuration Targeting:** +- Define configuration rules using tag criteria +- Deploy different configurations to different tag groups +- Support gradual canary rollouts via percentage-based tags +- Enable automatic rollback by removing devices from tags + +### Integration with XConf WebConfig Service + +**Device Query on Configuration Request:** +- WebConfig queries tags to determine applicable configs +- Uses tag membership to evaluate targeting rules +- Applies configuration changes based on tag presence +- Supports multi-tag device membership + +### Integration with Feature Control (RFC) + +**Feature Rollout Management:** +- RFC rules can target devices by tag membership +- Percentage-based distribution within tags +- A/B testing across tag populations +- Feature graduation: dev tag → beta tag → production tag + +### Integration with Telemetry + +**Data Collection Segmentation:** +- Telemetry profiles can target specific device tags +- Analytics segmentation by tag-based device groups +- Performance monitoring per device cohort +- Custom metrics collection for tagged device populations + +--- + +## Support and Resources + +- **API Documentation**: This document +- **Integration Guide**: See "API Integration Guide" section above +- **Troubleshooting**: See "Troubleshooting" section above +- **XConf Main Documentation**: Reference overview.md +- **Best Practices**: See "Best Practices" section above + +--- + +*Last Updated: January 2026* +*Version: 1.0* From 48627cb2fb5850388ed7650bc09fdd0a7d29033b Mon Sep 17 00:00:00 2001 From: LakshmipriyaPurushan <60867402+LakshmipriyaPurushan@users.noreply.github.com> Date: Tue, 20 Jan 2026 12:26:07 +0530 Subject: [PATCH 11/23] Add files via upload --- docs/tagging_service_API_documentation_new.md | 874 ++++-------------- 1 file changed, 201 insertions(+), 673 deletions(-) diff --git a/docs/tagging_service_API_documentation_new.md b/docs/tagging_service_API_documentation_new.md index e1cac42..d1edd1c 100644 --- a/docs/tagging_service_API_documentation_new.md +++ b/docs/tagging_service_API_documentation_new.md @@ -1,818 +1,346 @@ -# XConf Tagging Service API Documentation - -**Version:** 1.0 -**Last Updated:** January 2026 -**Base URL:** `/taggingService` -**Default Port:** 9001 - ---- +# XConf Tagging Service API ## Table of Contents -1. [Overview](#overview) -2. [Authentication](#authentication) -3. [Core Concepts](#core-concepts) -4. [API Endpoints](#api-endpoints) -5. [Data Models](#data-models) -6. [Request/Response Examples](#requestresponse-examples) -7. [Error Handling](#error-handling) -8. [Usage Patterns](#usage-patterns) -9. [Best Practices](#best-practices) - ---- - -## Overview - -The XConf Tagging Service API provides comprehensive tag management capabilities for device grouping and configuration targeting. It enables dynamic device categorization through tag-based systems, supporting both individual member management and percentage-based distribution for advanced deployment strategies. - -### Key Capabilities - -- **Tag Management**: Create, read, update, and delete device tags -- **Member Management**: Add/remove individual or batch members to/from tags -- **Tag Queries**: Retrieve tags by ID, list all tags, find tags containing specific members -- **Percentage-Based Distribution**: Calculate deterministic percentage values for devices to enable percentage-based rollouts -- **Batch Operations**: Efficiently manage large numbers of devices in single API calls -- **Real-time Updates**: Immediate availability of tag changes across all services - -### Service Architecture - -The Tagging Service operates independently and provides direct tag management without intermediate caching layers, ensuring immediate consistency across the XConf platform. +1. [Performance Information](#performance-information) + - [Add Members API](#add-members-api) + - [Delete Members API](#delete-members-api) +2. [API Endpoints](#api-endpoints) + - [SAT Token Requirements](#sat-token-requirements) + - [Get Tag by ID](#get-tag-by-id) + - [Delete Tag by ID (Asynchronous)](#delete-tag-by-id-asynchronous) + - [Add Members to Tag](#add-members-to-tag) + - [Remove Members from Tag](#remove-members-from-tag) + - [Remove Member from Tag](#remove-member-from-tag) + - [Get Tag Members](#get-tag-members) +3. [XConf Rule Configuration with Tags](#xconf-rule-configuration-with-tags) --- -## Authentication - -All endpoints require authentication via JWT token or session-based authentication. +## Performance Information -### Authentication Header Format +### Add Members API -``` -Authorization: Bearer -``` +The Add Members API processes member additions in batches, with each batch supporting up to 2,000 members. -### Authentication Requirements +### Delete Members API -- **JWT Tokens**: Must be valid and non-expired -- **Session-based**: Valid session credentials required -- **Role-based Access Control**: Operations require appropriate permissions -- **Service-to-Service**: SAT (Security Access Token) for inter-service communication +The Delete Members API also operates in batches of up to 2,000 members per batch. --- -## Core Concepts - -### Tags - -A tag is a named grouping mechanism for devices. Tags can contain multiple device members and are identified by a unique string identifier. - -**Tag Characteristics:** -- Unique identifier (string) -- List of member identifiers (device addresses, IDs, etc.) -- Last updated timestamp -- No size limitations (though practical limits apply) - -### Members - -Members are individual devices identified by: -- MAC addresses (e.g., `AA:BB:CC:DD:EE:FF`) -- Device IDs (e.g., `device_12345`) -- Account IDs (e.g., `account_67890`) -- Any custom string identifier +## API Endpoints -### Percentage Distribution +### SAT Token Requirements -Percentage values are calculated deterministically using SipHash algorithm, enabling consistent percentage-based device selection for: -- Canary deployments -- A/B testing -- Gradual rollouts -- Statistical device sampling +Client should have following SAT capabilities: +- `"x1:coast:cmtagds:assign"` +- `"x1:coast:cmtagds:read"` +- `"x1:coast:cmtagds:unassign"` +- `"x1:coast:xconf:read"` +- `"x1:coast:xconf:read:maclist"` +- `"x1:coast:xconf:write"` +- `"x1:coast:xconf:write:maclist"` --- -## API Endpoints - -### 1. Get All Tags +### Get Tag by ID -Retrieve all available tags in the system with optional full object expansion. +Returns representation of XConf tag by provided tag id -**Request:** +**Endpoint:** ``` -GET /taggingService/tags -GET /taggingService/tags?full +GET /taggingService/tags/{id} ``` -**Query Parameters:** - -| Parameter | Type | Required | Description | -|-----------|------|----------|-------------| -| `full` | flag | No | Returns complete tag objects with members instead of just tag IDs | - -**Response (without `full`):** -```json -[ - "production_devices", - "beta_testers", - "development_units", - "canary_group_1" -] +**Headers:** ``` +Accept = application/json +Content-Type = application/json +Authorization = Bearer {SAT token} +``` + +**Response Status Codes:** +- `200 OK` +- `404 NOT FOUND` -**Response (with `full`):** +**Response Body:** ```json -[ - { - "id": "production_devices", - "members": [ - "AA:BB:CC:DD:EE:01", - "AA:BB:CC:DD:EE:02", - "AA:BB:CC:DD:EE:03" - ], - "updated": 1699875600000 - }, - { - "id": "beta_testers", +{ + "id": "test:tag:demotag", + "description": "", "members": [ - "AA:BB:CC:DD:EE:10", - "AA:BB:CC:DD:EE:11" + "A2:A2:A2:A2:B2:B2" ], - "updated": 1699875500000 - } -] + "updated": 1711651165855 +} ``` -**HTTP Status Codes:** -- `200 OK`: Successfully retrieved tags -- `500 Internal Server Error`: Server-side processing error - --- -### 2. Get Tag by ID +### Delete Tag by ID (Asynchronous) -Retrieve a specific tag with complete information including all members and metadata. +Deletes a tag and all its members asynchronously. The API returns immediately after validation, and the actual deletion is processed in the background. -**Request:** +**Endpoint:** ``` -GET /taggingService/tags/{tag} +DELETE /taggingService/tags/{id} ``` -**Parameters:** +**Headers:** +``` +Accept = application/json +Content-Type = application/json +Authorization = Bearer {SAT token} +``` + +**Success Response (202 Accepted):** +The tag deletion request has been accepted and queued for processing. -| Parameter | Type | Location | Required | Description | -|-----------|------|----------|----------|-------------| -| `tag` | string | Path | Yes | Tag identifier | +**Status Code:** `202 Accepted` -**Response:** +**Response Body:** ```json { - "id": "production_devices", - "members": [ - "AA:BB:CC:DD:EE:01", - "AA:BB:CC:DD:EE:02", - "AA:BB:CC:DD:EE:03", - "AA:BB:CC:DD:EE:04" - ], - "updated": 1699875600000 + "status": "accepted", + "message": "Tag 'my-tag' deletion has been queued for processing", + "tag": "my-tag" } ``` -**HTTP Status Codes:** -- `200 OK`: Tag found and returned -- `400 Bad Request`: Invalid tag parameter -- `404 Not Found`: Tag does not exist -- `500 Internal Server Error`: Server processing error - ---- - -### 3. Delete Tag - -Delete a specific tag from the system completely. - -**Request:** -``` -DELETE /taggingService/tags/{tag} -``` - -**Parameters:** +#### Behavior -| Parameter | Type | Location | Required | Description | -|-----------|------|----------|----------|-------------| -| `tag` | string | Path | Yes | Tag identifier to delete | +- **Immediate Response:** API returns 202 Accepted immediately after validating that the tag exists +- **Background Processing:** Tag deletion (including all members and buckets) happens asynchronously +- **No Status Tracking:** Currently no endpoint to check deletion progress (work is pending) +- **Error Handling:** Any errors during background deletion are logged server-side -**Response:** -- No response body on successful deletion (HTTP 204) +#### Notes -**HTTP Status Codes:** -- `204 No Content`: Tag successfully deleted -- `400 Bad Request`: Invalid tag parameter -- `404 Not Found`: Tag not found -- `500 Internal Server Error`: Server processing error +- The 202 Accepted status indicates the request was valid and accepted, not that deletion is complete +- For large tags with many members, deletion may take several minutes +- Once accepted, the deletion cannot be cancelled --- -### 4. Add Members to Tag +### Add Members to Tag -Add multiple members to an existing tag in a batch operation. +Adds new members to the tag. If tag does not exist – new tag is created in XConf. By default XConf does tag member normalization: whitespaces are trimmed, string data is set to upper case. -**Request:** +**Endpoint:** ``` PUT /taggingService/tags/{tag}/members -Content-Type: application/json - -[ - "AA:BB:CC:DD:EE:05", - "AA:BB:CC:DD:EE:06", - "device_id_12345" -] ``` -**Parameters:** - -| Parameter | Type | Location | Required | Description | -|-----------|------|----------|----------|-------------| -| `tag` | string | Path | Yes | Tag identifier | -| Body | array | Request Body | Yes | Array of member identifiers (max 1000) | - -**Constraints:** -- Maximum 1000 members per request -- Exceeding limit returns 400 Bad Request -- Empty member list returns 400 Bad Request - -**Response:** -- Success confirmation with no response body (HTTP 200 OK) - -**HTTP Status Codes:** -- `200 OK`: Members successfully added -- `400 Bad Request`: Invalid input, batch size exceeded, or empty member list -- `404 Not Found`: Tag not found -- `500 Internal Server Error`: Server processing error - ---- - -### 5. Remove Single Member from Tag - -Remove a single member from a specific tag. - -**Request:** +**Headers:** ``` -DELETE /taggingService/tags/{tag}/members/{member} +Accept = application/json +Content-Type = application/json +Authorization = Bearer {SAT token} ``` -**Parameters:** +**Request Body - list of members:** +```json +["A1:A1:A1:A1:B1:B1", "A2:A2:A2:A2:B2:B2"] +``` -| Parameter | Type | Location | Required | Description | -|-----------|------|----------|----------|-------------| -| `tag` | string | Path | Yes | Tag identifier | -| `member` | string | Path | Yes | Member identifier to remove | +**Response Status Code:** `202 Accepted` -**Response:** +**Response Body - XConf tag entity with added members:** ```json { - "id": "production_devices", - "members": [ - "AA:BB:CC:DD:EE:01", - "AA:BB:CC:DD:EE:03", - "AA:BB:CC:DD:EE:04" - ], - "updated": 1699875700000 + "id": "test:tag:demotag", + "description": "", + "members": [ + "A1:A1:A1:A1:B1:B1", + "A2:A2:A2:A2:B2:B2" + ], + "updated": 1711651165855 } ``` -**HTTP Status Codes:** -- `200 OK`: Member successfully removed and tag returned -- `204 No Content`: Member successfully removed -- `400 Bad Request`: Invalid parameters -- `404 Not Found`: Tag or member not found -- `500 Internal Server Error`: Server processing error - --- -### 6. Remove Multiple Members from Tag +### Remove Members from Tag -Remove multiple members from a tag in a single batch operation. +Removes members from the tag. If all members are removed, the tag is automatically deleted. -**Request:** +**Endpoint:** ``` DELETE /taggingService/tags/{tag}/members -Content-Type: application/json - -[ - "AA:BB:CC:DD:EE:02", - "AA:BB:CC:DD:EE:05", - "device_id_old_123" -] ``` -**Parameters:** - -| Parameter | Type | Location | Required | Description | -|-----------|------|----------|----------|-------------| -| `tag` | string | Path | Yes | Tag identifier | -| Body | array | Request Body | Yes | Array of member identifiers to remove (max 1000) | - -**Constraints:** -- Maximum 1000 members per request -- Exceeding limit returns 400 Bad Request - -**Response:** -- No response body on successful removal (HTTP 204 No Content) - -**HTTP Status Codes:** -- `204 No Content`: Members successfully removed -- `400 Bad Request`: Invalid input or batch size exceeded -- `404 Not Found`: Tag not found -- `500 Internal Server Error`: Server processing error - ---- - -### 7. Get Tag Members - -Retrieve all members of a specific tag. - -**Request:** +**Headers:** ``` -GET /taggingService/tags/{tag}/members +Accept = application/json +Content-Type = application/json +Authorization = Bearer {SAT token} ``` -**Parameters:** - -| Parameter | Type | Location | Required | Description | -|-----------|------|----------|----------|-------------| -| `tag` | string | Path | Yes | Tag identifier | - -**Response:** +**Request Body - list of members:** ```json -[ - "AA:BB:CC:DD:EE:01", - "AA:BB:CC:DD:EE:02", - "AA:BB:CC:DD:EE:03", - "AA:BB:CC:DD:EE:04", - "device_id_12345", - "device_id_67890" -] +["A1:A1:A1:A1:B1:B1", "A2:A2:A2:A2:B2:B2"] ``` -**HTTP Status Codes:** -- `200 OK`: Members successfully retrieved -- `400 Bad Request`: Invalid tag parameter -- `404 Not Found`: Tag not found -- `500 Internal Server Error`: Server processing error +**Response Status Codes:** +- `404 NOT FOUND` +- `204 NO CONTENT` --- -### 8. Get Tags by Member +### Remove Member from Tag -Retrieve all tags containing a specific member. +Removes member record from XDAS first, in case of success removes tag member from XConf. Remove API takes non-normalized data, normalization is done by XConf. -**Request:** +**Endpoint:** ``` -GET /taggingService/tags/members/{member} -``` - -**Parameters:** - -| Parameter | Type | Location | Required | Description | -|-----------|------|----------|----------|-------------| -| `member` | string | Path | Yes | Member identifier to search for | - -**Response:** -```json -[ - { - "id": "production_devices", - "members": [ - "AA:BB:CC:DD:EE:01", - "AA:BB:CC:DD:EE:02", - "other_device_ids..." - ], - "updated": 1699875600000 - }, - { - "id": "priority_group", - "members": [ - "AA:BB:CC:DD:EE:01", - "priority_device_ids..." - ], - "updated": 1699875550000 - } -] +DELETE /taggingService/tags/{tag}/members/{member} ``` -**HTTP Status Codes:** -- `200 OK`: Tags successfully retrieved -- `400 Bad Request`: Invalid member parameter -- `404 Not Found`: Member not found in any tags -- `500 Internal Server Error`: Server processing error - ---- - -### 9. Calculate Percentage Value for Member - -Calculate deterministic percentage value for a member using SipHash algorithm. - -**Request:** +**Headers:** ``` -GET /taggingService/tags/members/{member}/percentages/calculation -``` - -**Parameters:** - -| Parameter | Type | Location | Required | Description | -|-----------|------|----------|----------|-------------| -| `member` | string | Path | Yes | Member identifier for calculation | - -**Algorithm Details:** -- **Name**: SipHash-2-4 -- **Key Configuration**: Fixed keys for consistent results -- **Output Range**: 0-99 (deterministic percentage value) -- **Use Case**: Percentage-based device rollout strategies -- **Deterministic**: Same member always returns same percentage value - -**Response:** -```json -67 +Accept = application/json +Content-Type = application/json +Authorization = Bearer {SAT token} ``` -**HTTP Status Codes:** -- `200 OK`: Percentage calculated successfully -- `400 Bad Request`: Invalid member parameter -- `500 Internal Server Error`: Server processing error +**Response Status Code:** `204 NO CONTENT` --- -## Data Models +### Get Tag Members -### Tag Object +Retrieves all members of a specified tag. Supports both non-paginated (V1 compatible) and paginated responses. -```json -{ - "id": "string", // Unique tag identifier (required) - "members": ["string"], // Array of member identifiers - "updated": "integer" // Unix timestamp (milliseconds) of last update -} +**Endpoint:** ``` - -**Field Details:** - -| Field | Type | Required | Description | -|-------|------|----------|-------------| -| `id` | string | Yes | Unique identifier for the tag | -| `members` | array | No | Array of device MAC addresses, device IDs, or identifiers | -| `updated` | integer | No | Unix timestamp in milliseconds of last modification | - -### Member Identifier Formats - -Supported member identifier formats: - -| Format | Example | Description | -|--------|---------|-------------| -| MAC Address | `AA:BB:CC:DD:EE:FF` | 48-bit hardware address in colon-separated hex | -| Device ID | `device_12345` | Alphanumeric device identifier | -| Account ID | `account_67890` | Account or subscription identifier | -| Custom String | `custom_identifier_1` | Any string-based identifier | - ---- - -## Request/Response Examples - -### Example 1: Create and Populate a Canary Tag - -**Step 1: Add devices to canary tag** - -```bash -curl -X PUT "http://localhost:9001/taggingService/tags/canary_group_1/members" \ - -H "Content-Type: application/json" \ - -H "Authorization: Bearer " \ - -d '[ - "AA:BB:CC:DD:EE:01", - "AA:BB:CC:DD:EE:02", - "AA:BB:CC:DD:EE:03" - ]' +GET /taggingService/tags/{tag}/members ``` -**Step 2: Verify tag members** - -```bash -curl -X GET "http://localhost:9001/taggingService/tags/canary_group_1/members" \ - -H "Authorization: Bearer " +**Headers:** ``` - -**Step 3: Calculate percentages for devices** - -```bash -curl -X GET "http://localhost:9001/taggingService/tags/members/AA:BB:CC:DD:EE:01/percentages/calculation" \ - -H "Authorization: Bearer " +Accept = application/json +Content-Type = application/json +Authorization = Bearer {SAT token} ``` -### Example 2: Batch Update Production Devices +#### Query Parameters (Optional - for pagination) -```bash -# Add devices -curl -X PUT "http://localhost:9001/taggingService/tags/production_devices/members" \ - -H "Content-Type: application/json" \ - -H "Authorization: Bearer " \ - -d '[ - "device_prod_001", - "device_prod_002", - "device_prod_003", - "device_prod_004", - "device_prod_005" - ]' - -# Remove outdated device -curl -X DELETE "http://localhost:9001/taggingService/tags/production_devices/members" \ - -H "Content-Type: application/json" \ - -H "Authorization: Bearer " \ - -d '[ - "device_prod_001" - ]' - -# Get all production devices -curl -X GET "http://localhost:9001/taggingService/tags/production_devices/members" \ - -H "Authorization: Bearer " -``` - -### Example 3: Find All Tags for a Device +| Parameter | Type | Required | Default | Maximum | Description | +|-----------|------|----------|---------|---------|-------------| +| `limit` | integer | No | 500 | 5000 | Number of members to return per page. Must be a positive integer. If exceeds maximum, returns 400 Bad Request | +| `cursor` | string | No | - | - | Pagination cursor for retrieving the next page of results. Obtained from nextCursor field in the previous response | -```bash -curl -X GET "http://localhost:9001/taggingService/tags/members/device_prod_002" \ - -H "Authorization: Bearer " -``` +**Note:** If either limit or cursor is provided, the endpoint returns a paginated response. Otherwise, it returns a non-paginated response. ---- +#### Response Status Codes -## Error Handling +- `200 OK`: Successfully retrieved members +- `206 Partial Content`: Response contains only first 100,000 members (tag has more than 100k members) +- `400 Bad Request`: Invalid tag or query parameters +- `404 Not Found`: Tag does not exist -### Common Error Responses +#### Non-Paginated Response Body -**400 Bad Request - Missing Tag** ```json -{ - "status": 400, - "message": "tag is not specified" -} +[ + "A2:A2:A2:A2:B2:B2" +] ``` -**400 Bad Request - Empty Member List** -```json -{ - "status": 400, - "message": "member list is empty" -} -``` +**Important:** In non-paginated mode, if a tag has more than 100,000 members, the response will be truncated to the first 100,000 members and the status code will be 206 Partial Content. To retrieve all members of large tags, use paginated mode. -**400 Bad Request - Batch Size Exceeded** -```json -{ - "status": 400, - "message": "batch size 1500 exceeds the limit of 1000" -} -``` +#### Paginated Mode -**404 Not Found** -```json -{ - "status": 404, - "message": "production_devices tag not found" -} -``` +Used when limit and/or cursor query parameters are provided. + +**Response Status Codes:** +- `200 OK`: Successfully retrieved page of members +- `400 Bad Request`: Invalid query parameters or tag parameter +- `404 Not Found`: Tag does not exist -**500 Internal Server Error** +**Response Body:** ```json { - "status": 500, - "message": "Internal server error occurred while processing the request" + "data": [ + "A2:A2:A2:A2:B2:B2", + "C3:C3:C3:C3:D3:D3", + "E4:E4:E4:E4:F4:F4" + ], + "nextCursor": "eyJidWNrZXQiOjEyLCJsYXN0S2V5IjoiQTI6QTI6QTI6QTI6QjI6QjIifQ==", + "hasMore": true } ``` -### HTTP Status Code Reference - -| Code | Status | Description | -|------|--------|-------------| -| 200 | OK | Request successful | -| 204 | No Content | Successful deletion/removal | -| 400 | Bad Request | Invalid input, missing parameters, batch size exceeded | -| 401 | Unauthorized | Authentication failed or missing token | -| 404 | Not Found | Resource not found | -| 500 | Internal Server Error | Server-side processing error | - ---- - -## Usage Patterns - -### Pattern 1: Percentage-Based Rollout - -``` -1. Create/identify target tag: "firmware_v2.1_rollout" -2. Add devices to tag in batches of 1000 -3. For each device, calculate percentage value -4. Select devices where percentage < 10 for initial rollout -5. Monitor rollout success -6. Gradually increase percentage threshold (10 → 25 → 50 → 100) -7. Remove tag when rollout complete -``` +**Response Fields:** +- `data` (array of strings): List of member identifiers in the current page +- `nextCursor` (string, optional): Cursor for the next page. Omitted if there are no more results. +- `hasMore` (boolean): Indicates whether more results are available + - `true`: More members available, use nextCursor to retrieve next page + - `false`: No more members to retrieve -### Pattern 2: A/B Testing Scenarios +##### Example Requests +**Non-Paginated (all members, up to 100k):** ``` -1. Create two tags: "feature_old_version" and "feature_new_version" -2. Add 50% of devices to each tag -3. Use percentage calculation for consistent split -4. Monitor metrics for both groups -5. Compare outcomes -6. Migrate all devices to winning version -7. Remove losing version tag +GET /taggingService/tags/my-tag-123/members ``` -### Pattern 3: Device Segmentation by Model - +**Paginated (first page with custom limit):** ``` -1. Create model-specific tags: - - "model_x1_devices" - - "model_x2_devices" - - "model_x3_devices" -2. Populate tags during device registration -3. Query tags by device to determine applicable configs -4. Remove devices from old model tags when replaced +GET /taggingService/tags/my-tag-123/members?limit=1000 ``` -### Pattern 4: Geographic Distribution - +**Paginated (subsequent page):** ``` -1. Create region-specific tags: - - "region_us_west_devices" - - "region_us_east_devices" - - "region_eu_devices" -2. Assign devices based on registration location -3. Deploy region-specific configurations -4. Monitor regional performance metrics +GET /taggingService/tags/my-tag-123/members?limit=1000&cursor=eyJidWNrZXQiOjEyLCJsYXN0S2V5IjoiQTI6QTI6QTI6QTI6QjI6QjIifQ== ``` ---- +##### Pagination Workflow -## Best Practices - -### Tag Naming Conventions - -✓ **Do:** -- Use lowercase with underscores: `production_devices`, `beta_testers` -- Include environment prefix: `prod_`, `staging_`, `dev_` -- Use descriptive names: `model_x1_devices`, `region_us_west` -- Keep names concise (max 64 characters recommended) -- Use consistent naming patterns - -✗ **Don't:** -- Use special characters (except underscores) -- Create ambiguous names without context -- Mix naming conventions in same system -- Use names that are too long - -### Member Management - -**Batch Operations:** -- Use batch operations for multiple members -- Maximum 1000 members per request -- Split large operations into multiple requests -- Prefer PUT/DELETE over individual operations - -**Validation:** -- Validate member identifiers before adding -- Ensure consistency in identifier format -- Remove duplicate members before adding -- Check for typos in device IDs - -**Monitoring:** -- Track tag membership changes -- Audit tag modifications -- Monitor tag sizes and growth -- Alert on unexpected changes - -### Performance Considerations - -**Query Optimization:** -- Use `/tags?full` only when needed -- Query specific tags rather than listing all -- Cache tag data locally when appropriate -- Batch read operations - -**Scaling:** -- Split large tags if exceeding 10,000 members -- Use logical tag hierarchies for organization -- Monitor API response times -- Implement client-side caching - -### Security Best Practices - -**Authentication:** -- Always use valid JWT tokens -- Rotate tokens regularly -- Use secure token storage -- Implement token expiration - -**Authorization:** -- Verify user permissions before operations -- Implement least-privilege access -- Audit all tag modifications -- Log sensitive operations - -**Input Validation:** -- Validate all member identifiers -- Sanitize tag names -- Check batch sizes -- Verify request parameters +1. Make initial request with optional limit parameter +2. Process the data array containing members +3. Check hasMore field: + - If `true`: Use the nextCursor value as the cursor parameter in the next request + - If `false`: All members have been retrieved +4. Repeat until hasMore is false --- -## Rate Limiting and Quotas - -| Resource | Limit | Notes | -|----------|-------|-------| -| Batch Member Operations | 1000 members/request | Split into multiple requests if needed | -| Tag Name Length | 256 characters | Recommended max: 64 characters | -| Member ID Length | 256 characters | Depends on identifier format | -| Concurrent Connections | Per server config | Default: 100 connections | -| API Request Rate | Unlimited | Subject to authentication limits | -| Tag Count | No documented limit | Monitor system performance | -| Members per Tag | No documented limit | Recommend splitting if > 10,000 | - ---- +## XConf Rule Configuration with Tags -## Troubleshooting +### Steps to Configure Rules with Tags -### Common Issues +1. **Create New Firmware Rule with the tag as the condition using EXISTS operation.** -**Issue: 404 Tag Not Found** -- Verify tag name spelling and case sensitivity -- Check if tag was recently deleted -- List all available tags: `GET /taggingService/tags` +2. **Add needed MAC address or any other parameters to the tag using "Add member to tag" API:** -**Issue: 400 Batch Size Exceeded** -- Split requests into chunks of max 1000 members -- Use loop to add members in batches -- Validate batch size before sending - -**Issue: 401 Unauthorized** -- Verify JWT token validity and expiration -- Check Authorization header format: `Bearer ` -- Regenerate token if expired - -**Issue: Member Not Found in Percentage Calculation** -- Verify member exists in at least one tag -- Check member identifier format -- Ensure no special character escaping issues - -**Issue: Slow Tag Queries** -- Reduce tag size by splitting into multiple tags -- Use specific tag queries instead of listing all -- Implement client-side caching -- Check network connectivity - ---- - -## API Integration Guide - -### Integration with XConf Admin Service - -**Tag-based Configuration Targeting:** -- Define configuration rules using tag criteria -- Deploy different configurations to different tag groups -- Support gradual canary rollouts via percentage-based tags -- Enable automatic rollback by removing devices from tags - -### Integration with XConf WebConfig Service - -**Device Query on Configuration Request:** -- WebConfig queries tags to determine applicable configs -- Uses tag membership to evaluate targeting rules -- Applies configuration changes based on tag presence -- Supports multi-tag device membership - -### Integration with Feature Control (RFC) - -**Feature Rollout Management:** -- RFC rules can target devices by tag membership -- Percentage-based distribution within tags -- A/B testing across tag populations -- Feature graduation: dev tag → beta tag → production tag - -### Integration with Telemetry - -**Data Collection Segmentation:** -- Telemetry profiles can target specific device tags -- Analytics segmentation by tag-based device groups -- Performance monitoring per device cohort -- Custom metrics collection for tagged device populations +```bash +curl --location --request PUT 'http:///taggingService/tags/xconf:tag:usage:demo/members' \ + --header 'Authorization: Bearer ' \ + --header 'Accept: application/json' \ + --header 'Content-Type: application/json' \ + --data '["BB:BB:BB:BB:BB:BB"]' +``` ---- +3. **Trigger /swu/xconf/ API to evaluate the rules, make sure that tag member from step 2 is present as in the request parameters of /swu/xconf/ query:** -## Support and Resources +```bash +curl --location 'http:///xconf/swu/stb?model=TESTMODEL&eStbMac=BB%3ABB%3ABB%3ABB%3ABB%3ABB&firmwareVersion=TEST_VERSION' +``` -- **API Documentation**: This document -- **Integration Guide**: See "API Integration Guide" section above -- **Troubleshooting**: See "Troubleshooting" section above -- **XConf Main Documentation**: Reference overview.md -- **Best Practices**: See "Best Practices" section above +**Example Response:** +```json +{ + "firmwareDownloadProtocol": "tftp", + "firmwareFilename": "filename.t", + "firmwareVersion": "TEST_VERSION_TAGGING_USAGE", + "mandatoryUpdate": false, + "rebootImmediately": false +} +``` --- +*Document Version: 1.0* *Last Updated: January 2026* -*Version: 1.0* From c23d85b0e68012b2d6d703186874bac24c2b06e4 Mon Sep 17 00:00:00 2001 From: LakshmipriyaPurushan <60867402+LakshmipriyaPurushan@users.noreply.github.com> Date: Tue, 20 Jan 2026 12:41:20 +0530 Subject: [PATCH 12/23] Add files via upload --- docs/xconfadmin_API_Documentation_new.md | 1183 ++++++++++++++++++++++ 1 file changed, 1183 insertions(+) create mode 100644 docs/xconfadmin_API_Documentation_new.md diff --git a/docs/xconfadmin_API_Documentation_new.md b/docs/xconfadmin_API_Documentation_new.md new file mode 100644 index 0000000..741bf5d --- /dev/null +++ b/docs/xconfadmin_API_Documentation_new.md @@ -0,0 +1,1183 @@ +# XConf Admin REST API Documentation + +## Admin API Calling Changes + +Please note the below examples earlier were towards XConf DataService, but as of Oct 6th, 2021, these XConf APIs are considered Admin APIs, and are not available on the XConf DataService endpoint. These APIs are available on the XConf Admin Service. + +Also note that to communicate with XConf Admin API service you will need a SAT token as a Bearer Token in your RESTful API call. XConf Admin Service API endpoint is protected by Comcast firewall, so the endpoint is not visible to Internet, only client from Comcast ENTERPRISE networks can access this XConf admin service endpoint. If your application is not in the Comcast network, then it is required that the application be configured to communicate with XConf Admin service via CodeBig2. Request for xconf admin service credentials on CodeBig2 portal. + +Use the following prefix for the below APIs instead of http://:/: +``` +https://:9443/xconfAdminService/ +``` + +If communicating via CodeBig2, then use: +``` +https:///xconfAdminService/ +``` + +**Important Notes:** +- The http://:/queries/foo.json method of calling is not supported and will not be supported +- In the next major revision of XConf Admin service, all Admin API responses will default to "application/json" response format +- Application types "text/xml" or "application/xml" for XConf API is no longer supported + +--- + +## API Endpoints Overview + +### Firmware Config +- Retrieve a list of firmware configs +- Retrieve a single firmware config by id +- Retrieve firmware configs by modelId +- Create/update a firmware config +- Delete a firmware config by id + +### IP rules +- Retrieve an ip rule list +- Retrieve an ip rule by name +- Create/update an ip rule +- Delete an ip rule + +### Location filter +- Retrieve a location filter list +- Retrieve a location filter by name +- Create/update location filter +- Delete location filter by name + +### Download location filter +- Retrieve download location filter +- Update download location filter + +### Environment model rules +- Retrieve an environment model rule list +- Retrieve an environment model rule by name +- Create/update an environment model rule +- Delete an environment model rule + +### IP filter +- Retrieve an IP filter list +- Retrieve an ip filter by name +- Create/update an IP filter +- Delete IP filter + +### Percent filter +- Retrieve percent filter +- Retrieve percent filter field values +- Update percent filter +- Retrieve EnvModelPercentages +- Retrieve EnvModelPercentage by id +- Create envModelPercentage +- Update EnvModelPercentage +- Delete envModelPercentage + +### Time filter +- Retrieve time filter list +- Retrieve time filter by name +- Create/update time filter +- Delete time filter by name + +### Environment +- Retrieve an list of environments +- Retrieve environment by id +- Create an environment +- Delete environment by id + +### IP address group +- Retrieve an IP address group list +- Retrieve an IP address group by name +- Retrieve an IP address group by IP +- Create an IP address group +- Add data to IP Address Group (dev in progress) +- Delete data from IP Address Group (dev in progress) +- Delete an IP address group by id + +### Mac rule +- Retrieve a mac rule list (legacy) +- Retrieve a mac rule list (v2) +- Retrieve mac rule by name (legacy) +- Retrieve mac rule by name (v2) +- Retrieve mac rule by mac address (legacy) +- Retrieve mac rule by mac address (v2) +- Create/update mac rule +- Delete mac rule by name + +### Model +- Retrieve a model list +- Retrieve model by id +- Create model +- Update model description +- Delete model by id + +### NamespacedList +- Retrieve all NS lists +- Retrieve NS list by mac part +- Create a NS list +- Add data to NS list +- Delete data from NS list +- Delete an NS list by id + +### RebootImmediately filter +- Retrieve an RI filter list +- Retrieve and RI filter by rule name +- Create/update an RI filter +- Delete RI filter by name + +### FirmwareRuleTemplate +- Retrieve filtered templates +- Import firmware rule templates +- Create firmware rule template +- Updating firmware rule template +- Deleting Firmware rule template + +### FirmwareRule +- Retrieve all firmware rules +- Retrieve filtered firmware rules +- Import firmware rule +- Create firmware rule +- Update firmware Rule +- Delete firmware Rule + +### Feature +- Retrieve all features +- Retrieve filtered features +- Import feature +- Create feature +- Update feature +- Delete feature + +### Feature Rule +- Retrieve all feature rules +- Retrieve filtered feature rules +- Import feature rule +- Create feature rule +- Update feature rule +- Delete feature rule + +### Activation Minimum Version +- Retrieve all activation minimum versions +- Retrieve filtered activation minimum versions +- Import activation version +- Create activation minimum version +- Update activation minimum version +- Delete activation minimum version + +### Telemetry Profile +- Retrieve all Telemetry Profiles +- Retrieve Telemetry Profile +- Create Telemetry Profile +- Update Telemetry Profile +- Delete Telemetry Profile +- Add Telemetry Profile Entry +- Remove Telemetry Profile entry +- Create Telemetry Profile through pending changes +- Update Telemetry Profile with approval +- Delete Telemetry Profile with approval +- Add Telemetry Profile Entry with approval +- Remove Telemetry Profile entry with approval + +### Telemetry Profile 2.0 +- Retrieve all Telemetry 2.0 Profiles +- Retrieve Telemetry 2.0 Profile +- Create Telemetry 2.0 Profile +- Update Telemetry 2.0 Profile +- Delete Telemetry 2.0 Profile +- Create with approval +- Update with approval +- Delete with approval +- Telemetry 2.0 Profile Json Schema + +### Change API +- Approve by change ids (not supported in golang implementation) +- Approve by entity id (not supported in golang implementation) +- Cancel change +- Retrieve all changes + +### Change v2 API +- Approve by change ids (not supported in golang implementation) +- Approve by entity id (not supported in golang implementation) +- Cancel change +- Retrieve all changes + +--- + +## Firmware Config + +### Retrieve a list of firmware configs + +**GET** `http://:/queries/firmwares?applicationType={type}` + +**Headers:** +- Accept = application/json +- applicationType parameter is not required, default value is stb + +**Response:** 200 OK OR 400 BAD REQUEST + +**Request Example:** +``` +http://localhost:9091/queries/firmwares +``` + +**JSON Response:** +```json +{ + "id": "firmwareConfigId", + "description": "FirmwareDescription", + "supportedModelIds": [ + "MODELA" + ], + "firmwareFilename": "FirmwareFilename", + "firmwareVersion": "FirmwareVersion", + "properties": { + "testKey": "testValue" + } +} +``` + +### Retrieve a single firmware config by id + +**GET** `http://:/queries/firmwares/` + +**Headers:** +- Accept = application/json + +**Response:** 200 OK + +**Request Example:** +``` +http://localhost:9091/queries/firmwares/b65962b5-1481-4eed-a010-2abfa8c3bbfd +``` + +**JSON Response:** +```json +{ + "id": "b65962b5-1481-4eed-a010-2abfa8c3bbfd", + "updated": 1440492963476, + "description": "_-", + "supportedModelIds": [ + "YETST" + ], + "firmwareDownloadProtocol": "tftp", + "firmwareFilename": "_-", + "firmwareVersion": "_-", + "rebootImmediately": false, + "properties": { + "testKey": "testValue" + } +} +``` + +### Retrieve firmware configs by modelId + +**GET** `http://:/queries/firmwares/model/{modelId}?applicationType={type}` + +**Headers:** +- Accept = application/json +- applicationType parameter is not required, default value is stb + +**Response:** 200 OK OR 400 BAD REQUEST (if application type has a wrong value) + +**Request Example:** +``` +http://localhost:9091/queries/firmwares/model/YETST +``` + +**JSON Response:** +```json +[{ + "id": "b65962b5-1481-4eed-a010-2abfa8c3bbfd", + "updated": 1440492963476, + "description": "_-", + "supportedModelIds": [ + "YETST" + ], + "firmwareDownloadProtocol": "tftp", + "firmwareFilename": "_-", + "firmwareVersion": "_-", + "rebootImmediately": false, + "properties": { + "testKey": "testValue" + } +}] +``` + +### Create/update a firmware config + +If firmware config is missing it will be created, otherwise updated. For update operation id field is not needed. + +**POST** `http://:/updates/firmwares?applicationType={type}` + +**Headers:** +- Content-Type = application/json +- Accept = application/json +- applicationType param is not required, default value is stb + +**Response:** 200 OK and saved object; 400 BAD REQUEST (by validation error); 500 INTERNAL SERVER ERROR + +**Restrictions:** +- Description, file name, version, supported model should be not empty + +**Request Example:** +``` +http://localhost:9091/updates/firmwares +``` + +**JSON Request:** +```json +{ + "id": "b65962b5-1481-4eed-a010-2abfa8c3bbfd", + "updated": 1440492963476, + "description": "_-", + "supportedModelIds": [ + "YETST" + ], + "firmwareDownloadProtocol": "tftp", + "firmwareFilename": "_-", + "firmwareVersion": "_-", + "rebootImmediately": false, + "properties": { + "testKey": "testValue" + } +} +``` + +### Delete a firmware config by id + +**DELETE** `http://:/delete/firmwares/` + +**Headers:** +- Accept = application/json + +**Response:** 204 NO CONTENT and text message: Firmware config successfully deleted OR Config doesn't exist. + +**Request Example:** +``` +http://localhost:9091/delete/firmwares/b65962b5-1481-4eed-a010-2abfa8c3bbfd +``` + +--- + +## IP rules + +### Retrieve an ip rule list + +**GET** `http://:/queries/rules/ips?applicationType={type}` + +**Headers:** +- Accept = application/json +- Default value for applicationType parameter is stb + +**Response:** 200 OK OR 400 BAD REQUEST + +**Request Example:** +``` +http://localhost:9091/queries/rules/ips +``` + +**JSON Response:** +```json +[ + { + "id": "ddc07355-d253-4f6b-8b42-296819d0d094", + "name": "fsd", + "ipAddressGroup": { + "id": "2c184325-f9eb-4edc-85c3-5b6466fc3c5c", + "name": "test", + "ipAddresses": [ + "192.11.11.11" + ] + }, + "environmentId": "DEV", + "modelId": "YETST", + "noop": true, + "expression": { + "targetedModelIds": [], + "environmentId": "DEV", + "modelId": "YETST", + "ipAddressGroup": { + "id": "2c184325-f9eb-4edc-85c3-5b6466fc3c5c", + "name": "test", + "ipAddresses": [ + "192.11.11.11" + ] + } + } + } +] +``` + +### Retrieve an ip rule by name + +**GET** `http://:/queries/rules/ips/{ipRuleName}?applicationType={type}` + +**Headers:** +- Accept = application/json +- Default value for applicationType parameter is stb + +**Response:** 200 OK OR 400 BAD REQUEST + +**Request Example:** +``` +http://localhost:9091/queries/rules/ips/fsd +``` + +**JSON Response:** +```json +{ + "id": "ddc07355-d253-4f6b-8b42-296819d0d094", + "name": "fsd", + "ipAddressGroup": { + "id": "2c184325-f9eb-4edc-85c3-5b6466fc3c5c", + "name": "test", + "ipAddresses": [ + "192.11.11.11" + ] + }, + "environmentId": "DEV", + "modelId": "YETST", + "noop": true, + "expression": { + "targetedModelIds": [], + "environmentId": "DEV", + "modelId": "YETST", + "ipAddressGroup": { + "id": "2c184325-f9eb-4edc-85c3-5b6466fc3c5c", + "name": "test", + "ipAddresses": [ + "192.11.11.11" + ] + } + } +} +``` + +### Create/update an ip rule + +If IpRule is missing it will be created, otherwise updated. For update operation id field is not needed. + +**POST** `http://:/updates/rules/ips?applicationType={type}` + +**Headers:** +- Content-Type = application/json +- Accept = application/json + +**Response:** 200 OK and saved object; 400 BAD REQUEST; 500 INTERNAL SERVER ERROR + +**Restrictions:** +- Name, environmentId, modelId should be not empty +- IP address group should be specified + +**Request Example:** +``` +http://localhost:9091/updates/rules/ips +``` + +**JSON Request:** +```json +{ + "id": "ddc07355-d253-4f6b-8b42-296819d0d094", + "name": "fsd", + "ipAddressGroup": { + "id": "2c184325-f9eb-4edc-85c3-5b6466fc3c5c", + "name": "test", + "ipAddresses": [ + "192.11.11.11" + ] + }, + "environmentId": "DEV", + "modelId": "YETST", + "noop": true, + "expression": { + "targetedModelIds": [], + "environmentId": "DEV", + "modelId": "YETST", + "ipAddressGroup": { + "id": "2c184325-f9eb-4edc-85c3-5b6466fc3c5c", + "name": "test", + "ipAddresses": [ + "192.11.11.11" + ] + } + } +} +``` + +### Delete an ip rule + +**DELETE** `http://:/delete/rules/ips/{ipRuleName}?applicationType={type}` + +**Headers:** +- Accept = application/json +- applicationType parameter is not required, default value is stb + +**Response:** 204 NO CONTENT and message: IpRule successfully deleted OR Rule doesn't exists; 400 BAD REQUEST if applicationType is not valid + +**Request Example:** +``` +http://localhost:9091/delete/rules/ips/ruleName +``` + +--- + +## Location filter + +### Retrieve a location filter list + +**GET** `http://:/queries/filters/locations?applicationType={type}` + +**Headers:** +- Accept = application/json +- applicationType parameter is not required, default value is stb + +**Response:** 200 OK OR 400 BAD REQUEST if applicationType is not valid + +**Request Example:** +``` +http://localhost:9091/queries/filters/locations +``` + +**JSON Response:** +```json +[ + { + "ipAddressGroup": { + "id": "2c184325-f9eb-4edc-85c3-5b6466fc3c5c", + "name": "test", + "ipAddresses": [ + "192.11.11.11" + ] + }, + "environments": [], + "models": [], + "ipv6FirmwareLocation": "2001:0db8:11a3:09d7:1f34:8a2e:07a0:765d", + "httpLocation": "http://localhost:8080", + "forceHttp": true, + "id": "2ce1279b-bb25-4fda-9a34-fe8466bc2702", + "name": "name", + "boundConfigId": "95e75859-ae8f-4d6a-b758-11fefbe647e1", + "ipv4FirmwareLocation": "10.10.10.10" + } +] +``` + +### Retrieve a location filter by name + +**GET** `http://:/queries/filters/locations/{locationFilterName}?applicationType={type}` + +Or legacy endpoint: +**GET** `http://:/queries/filters/locations/byName/{locationFilterName}` + +**Headers:** +- Accept = application/json + +**Response:** 200 OK + +**Request Example:** +``` +http://localhost:9091/queries/filters/locations/name +``` + +**JSON Response:** +```json +[ + { + "ipAddressGroup": { + "id": "2c184325-f9eb-4edc-85c3-5b6466fc3c5c", + "name": "test", + "ipAddresses": [ + "192.11.11.11" + ] + }, + "environments": [], + "models": [], + "ipv6FirmwareLocation": "2001:0db8:11a3:09d7:1f34:8a2e:07a0:765d", + "httpLocation": "http://localhost:8080", + "forceHttp": true, + "id": "2ce1279b-bb25-4fda-9a34-fe8466bc2702", + "name": "name", + "boundConfigId": "95e75859-ae8f-4d6a-b758-11fefbe647e1", + "ipv4FirmwareLocation": "10.10.10.10" + } +] +``` + +### Create/update location filter + +If location filter is missing it will be created, otherwise updated. For update operation id field is not needed. + +**POST** `http://:/updates/filters/locations?applicationType={type}` + +**Headers:** +- Content-Type = application/json +- Accept = application/json +- applicationType parameter is not required, default value is stb + +**Response:** 200 OK and saved object; 400 BAD REQUEST; 500 INTERNAL SERVER ERROR + +**Restrictions:** +- Condition, models, environments, IPv4, location, any location (HTTP or firmware), IPv4/IPv6 should be valid + +**Request Example:** +``` +http://localhost:9091/updates/filters/locations +``` + +**JSON Request:** +```json +{ + "ipAddressGroup": { + "id": "2c184325-f9eb-4edc-85c3-5b6466fc3c5c", + "name": "test", + "ipAddresses": [ + "192.11.11.11" + ] + }, + "environments": [], + "models": [], + "ipv6FirmwareLocation": "2001:0db8:11a3:09d7:1f34:8a2e:07a0:765d", + "httpLocation": "http://localhost:8080", + "forceHttp": true, + "id": "2ce1279b-bb25-4fda-9a34-fe8466bc2702", + "name": "name", + "boundConfigId": "95e75859-ae8f-4d6a-b758-11fefbe647e1", + "ipv4FirmwareLocation": "10.10.10.10" +} +``` + +### Delete location filter by name + +**DELETE** `http://:/delete/filters/locations/{locationFilterName}?applicationType={type}` + +**Headers:** +- Accept = application/json + +**Response:** 204 NO CONTENT and message: Location filter successfully deleted OR Filter doesn't exist with name: ; 400 BAD REQUEST if applicationType is not valid + +**Request Example:** +``` +http://localhost:9091/delete/filters/location/name +``` + +--- + +## Download location filter + +### Retrieve download location filter + +**GET** `http://:/queries/filters/downloadlocation?applicationType={type}` + +**Headers:** +- Accept = application/json +- applicationType param is not required, default value is stb + +**Response:** 200 OK; 400 BAD REQUEST if applicationType is not valid + +**Request Example:** +``` +http://localhost:9091/queries/filters/downloadlocation +``` + +**JSON Response:** +```json +{ + "type": "com.comcast.xconf.estbfirmware.DownloadLocationRoundRobinFilterValue", + "id": "DOWNLOAD_LOCATION_ROUND_ROBIN_FILTER_VALUE", + "locations": [ + { + "locationIp": "10.10.10.10", + "percentage": 100.0 + } + ], + "ipv6locations": [], + "rogueModels": [], + "httpLocation": "lf.com", + "httpFullUrlLocation": "http://www.localhost.org", + "neverUseHttp": true, + "firmwareVersions": "??" +} +``` + +### Update download location filter + +**POST** `http://:/updates/filters/downloadlocation?applicationType={type}` + +**Headers:** +- Content-Type = application/json +- Accept = application/json +- applicationType param is not required, default value is stb + +**Response:** 200 OK and saved object; 400 BAD REQUEST; 500 INTERNAL SERVER ERROR + +**Restrictions:** +- Location URL, IPv4/IPv6 should be valid +- Percentage should be positive and within [0, 100] +- Locations should be not duplicated + +**Request Example:** +``` +http://localhost:9091/updates/filters/downloadlocation +``` + +**JSON Request:** +```json +{ + "type": "com.comcast.xconf.estbfirmware.DownloadLocationRoundRobinFilterValue", + "id": "DOWNLOAD_LOCATION_ROUND_ROBIN_FILTER_VALUE", + "updated": 1441287139144, + "locations": [ + { + "locationIp": "10.10.10.10", + "percentage": 100.0 + } + ], + "ipv6locations": [], + "rogueModels": [], + "httpLocation": "lf.com", + "httpFullUrlLocation": "http://www.localhost.org", + "neverUseHttp": true, + "firmwareVersions": "??" +} +``` + +--- + +## Environment model rules + +### Retrieve an environment model rule list + +**GET** `http://:/queries/rules/envModels?applicationType={type}` + +**Headers:** +- Accept = application/json +- applicationType param is not required, default value is stb + +**Response:** 200 OK; 400 BAD REQUEST if applicationType is not valid + +**Request Example:** +``` +http://localhost:9091/queries/rules/envModels +``` + +**JSON Response:** +```json +[ + { + "id": "12b620bd-2e74-4467-91e5-c29657022c05", + "name": "re", + "firmwareConfig": { + "id": "f0b7b35b-4b8e-4a15-9d66-91c4b3d575d1", + "description": "prav_Firm", + "supportedModelIds": [ + "PX013ANM", + "PX013ANC" + ], + "firmwareFilename": "PX013AN_2.1s11_VBN_HYBse-signed.bin", + "firmwareVersion": "PX013AN_2.1s11_VBN_HYBse-signed" + }, + "environmentId": "TEST", + "modelId": "PX013ANC" + } +] +``` + +### Retrieve an environment model rule by name + +**GET** `http://:/queries/rules/envModels/{envModelRuleName}?applicationType={type}` + +**Headers:** +- Accept = application/json + +**Response:** 200 OK; 400 BAD REQUEST if applicationType is not valid + +**Request Example:** +``` +http://localhost:9091/queries/rules/envModels/testName +``` + +**JSON Response:** +```json +{ + "id": "12b620bd-2e74-4467-91e5-c29657022c05", + "name": "testName", + "firmwareConfig": { + "id": "f0b7b35b-4b8e-4a15-9d66-91c4b3d575d1", + "description": "prav_Firm", + "supportedModelIds": [ + "PX013ANM", + "PX013ANC" + ], + "firmwareFilename": "PX013AN_2.1s11_VBN_HYBse-signed.bin", + "firmwareVersion": "PX013AN_2.1s11_VBN_HYBse-signed" + }, + "environmentId": "TEST", + "modelId": "PX013ANC" +} +``` + +### Create/update an environment model rule + +If EnvModelRule is missing it will be created, otherwise updated. For update operation id field is not needed. + +**POST** `http://:/updates/rules/envModels?applicationType={type}` + +**Headers:** +- Content-Type = application/json +- Accept = application/json +- applicationType param is not required, default value is stb + +**Response:** 200 OK and saved object; 400 BAD REQUEST; 500 INTERNAL SERVER ERROR + +**Restrictions:** +- Name, environment, model should be not empty +- Name is used only once +- Environment/model should not overlap each other + +**Request Example:** +``` +http://localhost:9091/updates/rules/envModels +``` + +**JSON Request:** +```json +{ + "id": "12b620bd-2e74-4467-91e5-c29657022c05", + "name": "testName", + "firmwareConfig": { + "id": "f0b7b35b-4b8e-4a15-9d66-91c4b3d575d1", + "description": "prav_Firm", + "supportedModelIds": [ + "PX013ANM", + "PX013ANC" + ], + "firmwareFilename": "PX013AN_2.1s11_VBN_HYBse-signed.bin", + "firmwareVersion": "PX013AN_2.1s11_VBN_HYBse-signed" + }, + "environmentId": "TEST", + "modelId": "PX013ANC" +} +``` + +### Delete an environment model rule + +**DELETE** `http://:/delete/rules/envModels/{envModelRuleName}?applicationType={type}` + +**Headers:** +- Accept = application/json +- applicationType param is not required, default value is stb + +**Response:** 204 NO CONTENT and message: Rule successfully deleted OR Rule doesn't exist with name: ; 400 if applicationType is not valid + +**Request Example:** +``` +http://localhost:9091/delete/rules/envModels/testName +``` + +--- + +## IP filter + +### Retrieve an IP filter list + +**GET** `http://:/queries/filters/ips?applicationType={type}` + +**Headers:** +- Accept = application/json +- applicationType param is not required, default value is stb + +**Response:** 200 OK; 400 BAD REQUEST + +**Request Example:** +``` +http://localhost:9091/queries/filters/ips +``` + +**JSON Response:** +```json +[ + { + "id": "8bdb3493-a18b-4230-9b25-fd44df38863b", + "name": "name", + "ipAddressGroup": { + "id": "2c184325-f9eb-4edc-85c3-5b6466fc3c5c", + "name": "test", + "ipAddresses": [ + "192.11.11.11" + ] + }, + "warehouse": false + } +] +``` + +### Retrieve an ip filter by name + +**GET** `http://:/queries/filters/ips/{ipFilterName}?applicationType={type}` + +**Headers:** +- Accept = application/json +- applicationType param is not required, default value is stb + +**Response:** 200 OK; 400 BAD REQUEST if applicationType is not valid + +**Request Example:** +``` +http://localhost:9091/queries/filters/ips/namef +``` + +**JSON Response:** +```json +{ + "id": "f9c5a6e8-d34f-4dc6-ae41-9016b70552ae", + "name": "namef", + "ipAddressGroup": { + "id": "2c184325-f9eb-4edc-85c3-5b6466fc3c5c", + "name": "test", + "ipAddresses": [ + "192.11.11.11" + ] + }, + "warehouse": false +} +``` + +### Create/update an IP filter + +If IpFilter is missing it will be created, otherwise updated. For update operation id field is not needed. + +**POST** `http://:/updates/filters/ips?applicationType={type}` + +**Headers:** +- Content-Type = application/json +- Accept = application/json +- applicationType param is not required, default value is stb + +**Response:** 200 OK and saved object; 400 BAD REQUEST; 500 INTERNAL SERVER ERROR + +**Restrictions:** +- Name, IP address group should be not empty + +**Request Example:** +``` +http://localhost:9091/updates/filters/ips +``` + +**JSON Request:** +```json +{ + "id": "f9c5a6e8-d34f-4dc6-ae41-9016b70552ae", + "name": "namef", + "ipAddressGroup": { + "id": "2c184325-f9eb-4edc-85c3-5b6466fc3c5c", + "name": "test", + "ipAddresses": [ + "192.11.11.11" + ] + }, + "warehouse": false +} +``` + +### Delete IP filter + +**DELETE** `http://:/delete/filters/ips/{ipFilterName}?applicationType={stb}` + +**Headers:** +- Accept = application/json +- applicationType param is not required, default value is stb + +**Response:** 204 NO CONTENT and message: IpFilter successfully deleted OR Filter doesn't exist with name: ; 400 BAD REQUEST if applicationType is not valid + +**Request Example:** +``` +http://localhost:9091/delete/filters/ips/namef +``` + +--- + +## Telemetry Profile 2.0 + +### Retrieve all Telemetry 2.0 Profiles + +**GET** `http://:/telemetry/v2/profile` + +**Headers:** +- Accept = application/json +- Content-Type = application/json + +**Response Codes:** 200 + +**Response Body:** List of Telemetry 2.0 Profiles + +```json +[{ + "id": "8fb459f6-044e-4c64-99ff-e0c7c1b4124b", + "updated": 1646687418358, + "name": "test", + "jsonconfig": "...", + "applicationType": "rdkcloud" +}] +``` + +### Retrieve Telemetry 2.0 Profile + +**GET** `http://:/telemetry/v2/profile/{id}` + +**Headers:** +- Accept = application/json +- Content-Type = application/json + +**Response Codes:** 200, 404 + +### Create Telemetry 2.0 Profile + +**POST** `http://:/telemetry/v2/profile` + +**Headers:** +- Accept = application/json +- Content-Type = application/json + +**Response Codes:** 201, 400, 409 + +**Request Body:** Telemetry 2.0 Profile with or without id + +### Update Telemetry 2.0 Profile + +**PUT** `http://:/telemetry/v2/profile` + +**Headers:** +- Accept = application/json +- Content-Type = application/json + +**Response Codes:** 200, 400, 404, 409 + +### Delete Telemetry 2.0 Profile + +**DELETE** `http://:/telemetry/v2/profile/{id}` + +**Headers:** +- Accept = application/json +- Content-Type = application/json + +**Response Codes:** 204, 404, 409 + +### Create with approval + +**POST** `http://:/telemetry/v2/profile/change` + +**Headers:** +- Accept = application/json +- Content-Type = application/json + +**Response Code:** 200, 400 + +**Response Body:** Telemetry 2.0 profile change entity + +### Update with approval + +**PUT** `http://:/telemetry/v2/profile/change` + +**Headers:** +- Accept = application/json +- Content-Type = application/json + +**Response Code:** 200, 400 + +**Response Body:** Telemetry 2.0 profile change entity + +### Delete with approval + +**DELETE** `http://:/telemetry/v2/profile/change/{profile id}` + +**Headers:** +- Accept = application/json +- Content-Type = application/json + +**Response Status:** 200, 404, 409 + +--- + +## Change v2 API + +### Approve by change ids (not supported in golang implementation) + +All not selected changes by entity id will be canceled. For example, there are two changes, "change A" and "change B", id of "change A" is sent to approve, in result "change A" will be approved and "change B" will be canceled. + +**POST** `http://:/change/v2/approve/byChangeIds` + +**Headers:** +- Accept = application/json +- Content-Type = application/json + +**Request Body:** Array with change ids +```json +["4705486f-2dcc-4ae9-a920-a45b33755993"] +``` + +**Response Codes:** 200, 404, 409 + +**Response Body:** Change id - error message object. If change successfully approve an empty object is returned + +### Approve by entity id (not supported in golang implementation) + +To approve all changes by entity id + +**GET** `http://:/change/v2/approve/byEntityId/{id}` + +**Response Codes:** 200, 404, 409 + +**Response Body:** Change id - error message object. If change successfully approve an empty object is returned + +### Cancel change + +**GET** `http://:/change/v2/cancel/{changeId}` + +**Response Status:** 200, 404 + +### Retrieve all changes + +**GET** `http://:/change/v2/all` + +**Headers:** +- Accept = application/json + +**Response Codes:** 200 + +**Response Body:** Array with all telemetry changes + +--- + +## Example: Telemetry 2.0 Profile Update with Approval + +This is an example of updating a Telemetry 2.0 Profile with approval: + +**Request:** +``` +PUT http://:/telemetry/v2/profile/change +``` + +**Response Body Example:** +```json +{ + "id": "c3fee291-5376-40cf-88a3-96aadaa0e28b", + "updated": 1659727767163, + "entityId": "8205d716-8e45-4570-a34b-f1ebe0bdc75e", + "entityType": "TELEMETRY_TWO_PROFILE", + "newEntity": { + "@type": "TelemetryTwoProfile", + "id": "8205d716-8e45-4570-a34b-f1ebe0bdc75e", + "updated": 1621625846548, + "name": "Test Telemetry 2.0 Profile name", + "jsonconfig": "...", + "applicationType": "stb" + }, + "oldEntity": { + "@type": "TelemetryTwoProfile", + "id": "8205d716-8e45-4570-a34b-f1ebe0bdc75e", + "updated": 1659727722268, + "name": "Test Telemetry 2.0 Profile name", + "jsonconfig": "...", + "applicationType": "stb" + }, + "operation": "UPDATE", + "author": "UNKNOWN_USER" +} +``` From 46dc366ae9c31677f172cc613dcb9bc56f2fe8d1 Mon Sep 17 00:00:00 2001 From: LakshmipriyaPurushan <60867402+LakshmipriyaPurushan@users.noreply.github.com> Date: Tue, 20 Jan 2026 14:28:59 +0530 Subject: [PATCH 13/23] Add files via upload --- docs/xconfadmin_API_Documentation_new.md | 1369 +++++++++++++++++++--- 1 file changed, 1178 insertions(+), 191 deletions(-) diff --git a/docs/xconfadmin_API_Documentation_new.md b/docs/xconfadmin_API_Documentation_new.md index 741bf5d..d7a80ec 100644 --- a/docs/xconfadmin_API_Documentation_new.md +++ b/docs/xconfadmin_API_Documentation_new.md @@ -1,202 +1,50 @@ # XConf Admin REST API Documentation -## Admin API Calling Changes +## Overview -Please note the below examples earlier were towards XConf DataService, but as of Oct 6th, 2021, these XConf APIs are considered Admin APIs, and are not available on the XConf DataService endpoint. These APIs are available on the XConf Admin Service. +The XConf Admin API provides comprehensive configuration management for RDK devices through a RESTful interface. It manages firmware configurations, device settings, telemetry profiles, feature rules, and various configuration management operations. -Also note that to communicate with XConf Admin API service you will need a SAT token as a Bearer Token in your RESTful API call. XConf Admin Service API endpoint is protected by Comcast firewall, so the endpoint is not visible to Internet, only client from Comcast ENTERPRISE networks can access this XConf admin service endpoint. If your application is not in the Comcast network, then it is required that the application be configured to communicate with XConf Admin service via CodeBig2. Request for xconf admin service credentials on CodeBig2 portal. +**Base URL**: `https://:9443/xconfAdminService/` -Use the following prefix for the below APIs instead of http://:/: -``` -https://:9443/xconfAdminService/ -``` - -If communicating via CodeBig2, then use: -``` -https:///xconfAdminService/ -``` - -**Important Notes:** -- The http://:/queries/foo.json method of calling is not supported and will not be supported -- In the next major revision of XConf Admin service, all Admin API responses will default to "application/json" response format -- Application types "text/xml" or "application/xml" for XConf API is no longer supported +**Authentication**: Most endpoints require authentication via SAT token as a Bearer Token in the Authorization header. --- -## API Endpoints Overview - -### Firmware Config -- Retrieve a list of firmware configs -- Retrieve a single firmware config by id -- Retrieve firmware configs by modelId -- Create/update a firmware config -- Delete a firmware config by id - -### IP rules -- Retrieve an ip rule list -- Retrieve an ip rule by name -- Create/update an ip rule -- Delete an ip rule - -### Location filter -- Retrieve a location filter list -- Retrieve a location filter by name -- Create/update location filter -- Delete location filter by name - -### Download location filter -- Retrieve download location filter -- Update download location filter - -### Environment model rules -- Retrieve an environment model rule list -- Retrieve an environment model rule by name -- Create/update an environment model rule -- Delete an environment model rule - -### IP filter -- Retrieve an IP filter list -- Retrieve an ip filter by name -- Create/update an IP filter -- Delete IP filter - -### Percent filter -- Retrieve percent filter -- Retrieve percent filter field values -- Update percent filter -- Retrieve EnvModelPercentages -- Retrieve EnvModelPercentage by id -- Create envModelPercentage -- Update EnvModelPercentage -- Delete envModelPercentage - -### Time filter -- Retrieve time filter list -- Retrieve time filter by name -- Create/update time filter -- Delete time filter by name - -### Environment -- Retrieve an list of environments -- Retrieve environment by id -- Create an environment -- Delete environment by id - -### IP address group -- Retrieve an IP address group list -- Retrieve an IP address group by name -- Retrieve an IP address group by IP -- Create an IP address group -- Add data to IP Address Group (dev in progress) -- Delete data from IP Address Group (dev in progress) -- Delete an IP address group by id - -### Mac rule -- Retrieve a mac rule list (legacy) -- Retrieve a mac rule list (v2) -- Retrieve mac rule by name (legacy) -- Retrieve mac rule by name (v2) -- Retrieve mac rule by mac address (legacy) -- Retrieve mac rule by mac address (v2) -- Create/update mac rule -- Delete mac rule by name - -### Model -- Retrieve a model list -- Retrieve model by id -- Create model -- Update model description -- Delete model by id - -### NamespacedList -- Retrieve all NS lists -- Retrieve NS list by mac part -- Create a NS list -- Add data to NS list -- Delete data from NS list -- Delete an NS list by id - -### RebootImmediately filter -- Retrieve an RI filter list -- Retrieve and RI filter by rule name -- Create/update an RI filter -- Delete RI filter by name - -### FirmwareRuleTemplate -- Retrieve filtered templates -- Import firmware rule templates -- Create firmware rule template -- Updating firmware rule template -- Deleting Firmware rule template - -### FirmwareRule -- Retrieve all firmware rules -- Retrieve filtered firmware rules -- Import firmware rule -- Create firmware rule -- Update firmware Rule -- Delete firmware Rule - -### Feature -- Retrieve all features -- Retrieve filtered features -- Import feature -- Create feature -- Update feature -- Delete feature - -### Feature Rule -- Retrieve all feature rules -- Retrieve filtered feature rules -- Import feature rule -- Create feature rule -- Update feature rule -- Delete feature rule - -### Activation Minimum Version -- Retrieve all activation minimum versions -- Retrieve filtered activation minimum versions -- Import activation version -- Create activation minimum version -- Update activation minimum version -- Delete activation minimum version - -### Telemetry Profile -- Retrieve all Telemetry Profiles -- Retrieve Telemetry Profile -- Create Telemetry Profile -- Update Telemetry Profile -- Delete Telemetry Profile -- Add Telemetry Profile Entry -- Remove Telemetry Profile entry -- Create Telemetry Profile through pending changes -- Update Telemetry Profile with approval -- Delete Telemetry Profile with approval -- Add Telemetry Profile Entry with approval -- Remove Telemetry Profile entry with approval - -### Telemetry Profile 2.0 -- Retrieve all Telemetry 2.0 Profiles -- Retrieve Telemetry 2.0 Profile -- Create Telemetry 2.0 Profile -- Update Telemetry 2.0 Profile -- Delete Telemetry 2.0 Profile -- Create with approval -- Update with approval -- Delete with approval -- Telemetry 2.0 Profile Json Schema - -### Change API -- Approve by change ids (not supported in golang implementation) -- Approve by entity id (not supported in golang implementation) -- Cancel change -- Retrieve all changes - -### Change v2 API -- Approve by change ids (not supported in golang implementation) -- Approve by entity id (not supported in golang implementation) -- Cancel change -- Retrieve all changes +## Table of Contents + +### Configuration Management +1. [Firmware Config](#firmware-config) +2. [IP Rules](#ip-rules) +3. [Location Filter](#location-filter) +4. [Download Location Filter](#download-location-filter) +5. [Environment Model Rules](#environment-model-rules) +6. [IP Filter](#ip-filter) +7. [Percent Filter](#percent-filter) +8. [Time Filter](#time-filter) +9. [RebootImmediately Filter](#rebootimmediately-filter) + +### Entity Management +10. [Environment](#environment) +11. [IP Address Group](#ip-address-group) +12. [Model](#model) +13. [NamespacedList](#namespacedlist) +14. [Mac Rule](#mac-rule) + +### Rule and Template Management +15. [FirmwareRuleTemplate](#firmwareruletemplate) +16. [FirmwareRule](#firmwarerule) +17. [Feature](#feature) +18. [Feature Rule](#feature-rule) +19. [Activation Minimum Version](#activation-minimum-version) + +### Telemetry Management +20. [Telemetry Profile](#telemetry-profile) +21. [Telemetry Profile 2.0](#telemetry-profile-20) +22. [Telemetry 2.0 Profile Json Schema](#telemetry-20-profile-json-schema) + +### Change Management +23. [Change API](#change-api) +24. [Change v2 API](#change-v2-api) --- @@ -993,6 +841,1145 @@ http://localhost:9091/delete/filters/ips/namef --- +## Percent Filter + +### Retrieve percent filter + +**GET** `http://:/queries/filters/percent?applicationType={type}` + +**Headers:** +- Accept = application/json +- applicationType param is not required, default value is stb + +**Response:** 200 OK; 400 BAD REQUEST if applicationType is not valid + +### Retrieve percent filter field values + +**GET** `http://:/queries/filters/percent?field=fieldName&applicationType={type}` + +**Headers:** +- Accept = application/json +- applicationType param is not required, default value is stb + +**Response:** 200 OK if field exists; 404 Not Found if field does not exist + +### Update percent filter + +**POST** `http://:/updates/filters/percent?applicationType={type}` + +**Headers:** +- Content-Type = application/json +- Accept = application/json +- applicationType param is not required, default value is stb + +**Response:** 200 OK and saved object; 400 BAD REQUEST; 500 INTERNAL SERVER ERROR + +**Restrictions:** +- Percentage should be positive and within [0, 100] + +### Retrieve EnvModelPercentages + +**GET** `http://:/queries/percentageBean?applicationType={type}` + +**Headers:** +- Content-Type = application/json +- Accept = application/json +- applicationType param is not required, default value is stb + +**Response:** 200 OK; 400 BAD REQUEST + +### Retrieve EnvModelPercentage by id + +**GET** `http://:/queries/percentageBean/id` + +**Headers:** +- Content-Type = application/json +- Accept = application/json + +**Response:** 200 OK OR 404 if envModelPercentage is not found + +### Create envModelPercentage + +**POST** `http://:/updates/percentageBean?applicationType={type}` + +**Headers:** +- Content-Type = application/json +- Accept = application/json +- applicationType param is not required, default value is stb + +**Response:** 200 OK; 404 NOT FOUND; 409 CONFLICT; 400 BAD REQUEST + +**Restrictions:** +- Name should be unique and not blank +- Environment and model should be not empty +- At least one firmware version should be in minCheck list if firmwareCheckRequired=true +- Percentage within [0, 100] +- Distribution firmware version should be in minCheck list if firmwareCheckRequired=true +- Total distribution percentage is within [0, 100] +- Last known good is not empty if total distribution percentage < 100 + +### Update EnvModelPercentage + +**PUT** `http://:/updates/percentageBean?applicationType={type}` + +**Headers:** +- Content-Type = application/json +- Accept = application/json +- applicationType param is not required, default value is stb + +**Response:** 200 OK; 404 NOT FOUND; 409 CONFLICT; 400 BAD REQUEST + +### Delete envModelPercentage + +**DELETE** `http://:/delete/percentageBean/id` + +**Headers:** +- Content-Type = application/json +- Accept = application/json + +**Response:** 204 NO CONTENT OR 404 NOT FOUND + +--- + +## Time Filter + +### Retrieve time filter list + +**GET** `http://:/queries/filters/time?applicationType={type}` + +**Headers:** +- Accept = application/json +- applicationType param is not required, default value is stb + +**Response:** 200 OK; 400 BAD REQUEST + +### Retrieve time filter by name + +**GET** `http://:/queries/filters/time/{name}?applicationType={type}` + +**Headers:** +- Accept = application/json +- applicationType param is not required, default value is stb + +**Response:** 200 OK; 400 BAD REQUEST + +### Create/update time filter + +If time filter is missing it will be created, otherwise updated. For update operation id field is not needed. + +**POST** `http://:/updates/filters/time?applicationType={type}` + +**Headers:** +- Content-Type = application/json +- Accept = application/json +- applicationType param is not required, default value is stb + +**Response:** 200 OK and saved object; 400 BAD REQUEST; 500 INTERNAL SERVER ERROR + +**Restrictions:** +- Name should be unique + +### Delete time filter by name + +**DELETE** `http://:/delete/filters/time/{timeFilterName}?applicationType={type}` + +**Headers:** +- Accept = application/json +- applicationType is not required, default value is stb + +**Response:** 204 NO CONTENT and message: Time Filter successfully deleted OR Filter doesn't exist with name: + +--- + +## RebootImmediately Filter + +### Retrieve an RI filter list + +**GET** `http://:/queries/filters/ri?applicationType={type}` + +**Headers:** +- Accept = application/json +- applicationType is not required, default value is stb + +**Response:** 200 OK; 400 BAD REQUEST + +### Retrieve an RI filter by rule name + +**GET** `http://:/queries/filters/ri/{ruleName}?applicationType={type}` + +**Headers:** +- Accept = application/json +- applicationType is not required, default value is stb + +**Response:** 200 OK; 400 BAD REQUEST + +### Create/update an RI filter + +If RI filter is missing it will be created, otherwise updated. For update operation id field is not needed. + +**POST** `http://:/updates/filters/ri?applicationType={type}` + +**Headers:** +- Accept = application/json +- applicationType is not required, default value is stb + +**Response:** 200 OK; 201 CREATED; 400 BAD REQUEST; 500 INTERNAL SERVER ERROR + +**Restrictions:** +- Name should be not empty +- At least one of filter criteria should be specified +- MAC addresses should be valid + +### Delete RI filter by name + +**DELETE** `http://:/delete/filters/ri/{riFilterName}?applicationType={type}` + +**Headers:** +- Accept = application/json +- applicationType is not required, default value is stb + +**Response:** 204 NO CONTENT and message: Filter does't exist OR Successfully deleted; 400 BAD REQUEST + +--- + +## Environment + +### Retrieve an list of environments + +**GET** `http://:/queries/environments` + +**Headers:** +- Accept = application/json + +**Response:** 200 OK + +**Request Example:** +``` +http://localhost:9091/queries/environments +``` + +**JSON Response:** +```json +[{"id":"DEV","description":"ff"},{"id":"TEST","description":"do not delete"}] +``` + +### Retrieve environment by id + +**GET** `http://:/queries/environments/` + +**Headers:** +- Accept = application/json + +**Response:** 200 OK; 400 BAD REQUEST + +**Request Example:** +``` +http://localhost:9091/queries/environments/DEV +``` + +### Create an environment + +**POST** `http://:/updates/environments` + +**Headers:** +- Content-Type: application/json +- Accept = application/json + +**Response:** 200 OK and saved object; 400 BAD REQUEST; 500 INTERNAL SERVER ERROR + +**Restrictions:** +- Environment name should be valid by pattern: ^[a-zA-Z0-9]+$ +- Name should be unique + +**Request Example:** +``` +http://localhost:9091/updates/environments +``` + +**JSON Request:** +```json +{"id":"testName","description":"some description"} +``` + +### Delete environment by id + +**DELETE** `http://:/delete/environments/` + +**Headers:** +- Accept = application/json + +**Response:** 204 NO CONTENT and message: Environment doesn't exist OR Environment successfully deleted; 400 BAD REQUEST: Environment is used: + +**Restrictions:** +- Environment should be not used + +--- + +## IP Address Group + +### Retrieve an IP address group list + +**GET** `http://:/queries/ipAddressGroups` + +**Headers:** +- Accept = application/json + +**Response:** 200 OK + +**Request Example:** +``` +http://localhost:9091/queries/ipAddressGroups +``` + +**JSON Response:** +```json +[ + { + "id": "2c184325-f9eb-4edc-85c3-5b6466fc3c5c", + "name": "test", + "ipAddresses": [ + "192.11.11.11" + ] + } +] +``` + +### Retrieve an IP address group by name + +**GET** `http://:/queries/ipAddressGroups/byName//` + +**Headers:** +- Accept = application/json + +**Response:** 200 OK; 400 BAD REQUEST + +### Retrieve an IP address group by IP + +**GET** `http://:/queries/ipAddressGroups/byIp//` + +**Headers:** +- Accept = application/json + +**Response:** 200 OK; 400 BAD REQUEST + +### Create an IP address group + +**POST** `http://:/updates/ipAddressGroups` + +**Headers:** +- Content-Type: application/json +- Accept = application/json + +**Response:** 200 OK and saved object; 400 BAD REQUEST; 500 INTERNAL SERVER ERROR + +**Restrictions:** +- Name should be not empty and unique + +### Add data to IP Address Group + +**POST** `http://:/updates/ipAddressGroups//addData` + +**Headers:** +- Content-Type = application/json +- Accept = application/json + +**Response:** 200 OK and ipAddressGroup object; 400 BAD REQUEST; 500 INTERNAL SERVER ERROR + +**Restrictions:** +- ipAddressGroup with current id should exist + +### Delete data from IP Address Group + +**POST** `http://:/updates/ipAddressGroups//removeData` + +**Headers:** +- Content-Type = application/json +- Accept = application/json + +**Response:** 204 NO CONTENT and ipAddressGroup object; 400 BAD REQUEST + +**Restrictions:** +- List contains IPs which should be present in current IP address group +- IP address group should contain at least one IP address + +### Delete an IP address group by id + +**DELETE** `http://:/delete/ipAddressGroups/` + +**Headers:** +- Accept = application/json + +**Response:** 204 NO CONTENT and message: IpAddressGroup doesn't exist OR IpAddressGroup successfully deleted; 400 BAD REQUEST: IpAddressGroup is used: + +**Restrictions:** +- IP address group should be not used + +--- + +## Model + +### Retrieve a model list + +**GET** `http://:/queries/models` + +**Headers:** +- Accept = application/json + +**Response:** 200 OK + +**Request Example:** +``` +http://localhost:9091/queries/models +``` + +**JSON Response:** +```json +[ + { + "id": "YETST", + "description": "" + }, + { + "id": "PX013ANC", + "description": "Pace XG1v3 - Cisco Cable Card" + } +] +``` + +### Retrieve model by id + +**GET** `http://:/queries/models/` + +**Headers:** +- Accept = application/json + +**Response:** 200 OK; 204 NO CONTENT + +### Create model + +**POST** `http://:/updates/models` + +**Headers:** +- Content-Type = application/json +- Accept = application/json + +**Response:** 201 CREATED; 400 BAD REQUEST; 500 INTERNAL SERVER ERROR + +**Restrictions:** +- Model name should be unique and valid by pattern: ^[a-zA-Z0-9]+$ + +### Update model description + +**PUT** `http://:/updates/models` + +**Headers:** +- Content-Type = application/json +- Accept = application/json + +**Response:** 200 OK; 400 BAD REQUEST; 404 NOT FOUND; 500 INTERNAL SERVER ERROR + +### Delete model by id + +**DELETE** `http://:/delete/models/` + +**Headers:** +- Accept = application/json + +**Response:** 204 NO CONTENT and message: Model deleted successfully; 404 NOT found and message "Model doesn't exist" + +**Restrictions:** +- Model should be not used in another places + +--- + +## NamespacedList + +### Retrieve all NS lists + +**GET** `http://:/queries/nsLists` + +**Headers:** +- Accept = application/json + +**Response:** 200 OK + +**Request Example:** +``` +http://localhost:9091/queries/nsLists +``` + +**JSON Response:** +```json +[ + { + "id": "macs", + "data": [ + "AA:AA:AA:AA:AA:AA" + ] + } +] +``` + +### Retrieve NS list by id + +**GET** `http://:/queries/nsLists/byId/` + +**Headers:** +- Accept = application/json + +**Response:** 200 OK + +### Retrieve NS list by mac part + +**GET** `http://:/queries/nsLists/byMacPart/` + +**Headers:** +- Accept = application/json + +**Response:** 200 OK + +### Create a NS list + +**POST** `http://:/updates/nsLists` + +**Headers:** +- Content-Type = application/json +- Accept = application/json + +**Response:** 201 CREATED; 400 BAD REQUEST; 500 INTERNAL SERVER ERROR + +**Restrictions:** +- Name should be valid by pattern: ^[a-zA-Z0-9]+$ +- List data should be not empty and contain valid mac addresses +- MAC address should be used only in one NS list + +### Add data to NS list + +**POST** `http://:/updates/nsLists//addData` + +Or legacy endpoint: +**POST** `http://:/updates/nslist//addData` + +**Headers:** +- Content-Type = application/json +- Accept = application/json + +**Response:** 200 OK and NS list object; 400 BAD REQUEST; 500 INTERNAL SERVER ERROR + +### Delete data from NS list + +**DELETE** `http://:/updates/nsLists//removeData` + +Or legacy endpoint: +**DELETE** `http://:/updates/nslist//removeData` + +**Headers:** +- Content-Type = application/json +- Accept = application/json + +**Response:** 204 NO CONTENT and NS list object; 400 BAD REQUEST + +**Restrictions:** +- List contains MACs which should be present in current Namespaced list +- Namespaced list should contain at least one MAC address + +### Delete an NS list by id + +**DELETE** `http://:/delete/nsLists/` + +**Headers:** +- Accept = application/json + +**Response:** 200 OK and message: NamespacedList doesn't exist OR NamespacedList successfully deleted + +**Restrictions:** +- NS list should be not used in another places + +--- + +## Mac Rule + +### Retrieve a mac rule list (legacy) + +**GET** `http://:/queries/rules/macs?applicationType={type}` + +**Headers:** +- Accept = application/json +- applicationType is not required, default value is stb + +**Response:** 200 OK; 400 BAD REQUEST + +**Note:** With no version parameter or version < 2. Legacy query. For each macrule returned, if it was created with multiple maclists, only the first one is returned in macListRef. + +### Retrieve a mac rule list (v2) + +**GET** `http://:/queries/rules/macs?version=2&applicationType={type}` + +**Headers:** +- Accept = application/json +- applicationType is not required, default value is stb + +**Response:** 200 OK; 400 BAD REQUEST + +**Note:** Version parameter could be any number >= 2. + +### Retrieve mac rule by name (legacy) + +**GET** `http://:/queries/rules/macs/` + +**Headers:** +- Accept = application/json + +**Response:** 200 OK + +### Retrieve mac rule by name (v2) + +**GET** `http://:/queries/rules/macs/?version=2&applicationType={type}` + +**Headers:** +- Accept = application/json + +**Response:** 200 OK + +### Retrieve mac rule by mac address (legacy) + +**GET** `http://:/queries/rules/macs/address/{macAddress}?applicationType={type}` + +**Headers:** +- Accept = application/json + +**Response:** 200 OK; 400 BAD REQUEST + +### Retrieve mac rule by mac address (v2) + +**GET** `http://:/queries/rules/macs/address/?version=2&applicationType={type}` + +**Headers:** +- Accept = application/json + +**Response:** 200 OK; 400 BAD REQUEST + +### Create/update mac rule + +For create operation id field is optional and the system will generate one in that case. If macrule corresponding to 'id' is missing, a new entry will be created. Otherwise existing entry is completely overwritten with the new parameters provided. + +**POST** `http://:/updates/rules/macs?applicationType={type}` + +**Headers:** +- Content-Type = application/json +- Accept = application/json +- applicationType is not required, default value is stb + +**Response:** 200 OK; 201 CREATED; 400 BAD REQUEST; 500 INTERNAL SERVER ERROR + +**Restrictions:** +- Name, mac address list, model list, mac list, firmware configuration should be not empty +- MAC address list is never used in another rule +- Model list contain only existed model +- Firmware config should support given models + +### Delete mac rule by name + +**DELETE** `http://:/delete/rules/macs/{macRuleName}?applicationType={type}` + +**Headers:** +- Accept = application/json +- applicationType is not required, default value is stb + +**Response:** 204 NO CONTENT and message: MacRule does'n exist OR MacRule deleted successfully; 400 BAD REQUEST + +--- + +## FirmwareRuleTemplate + +### Retrieve filtered templates + +**GET** `http://:/firmwareruletemplate/filtered?name=MAC_RULE&key=someKey` + +**Headers:** +- Accept = application/json +- Content-Type = application/json + +**Request Parameters:** +- Without params: Retrieve all firmware rule templates +- `name`: Filter templates by name +- `key`: Filter by rule key +- `value`: Filter by rule value +- Parameters can be combined: `?name=someName&value=testValue` + +**Response Codes:** 200 + +### Import firmware rule templates + +**POST** `http://:/firmwareruletemplate/importAll` + +**Headers:** +- Accept = application/json +- Content-Type = application/json + +**Request Body:** List of firmware rule templates + +**Response Codes:** 200, 400, 404, 409 + +**Response Body:** +```json +{ + "NOT_IMPORTED": [], + "IMPORTED": [] +} +``` + +### Create firmware rule template + +**POST** `http://:/firmwareruletemplate/?applicationType=stb` + +**Headers:** +- Accept = application/json +- Content-Type = application/json +- Authorization = Bearer {SAT token} + +**Response Status:** 201 Created + +### Update firmware rule template + +**POST** `http://:/firmwareruletemplate/?applicationType=stb` + +**Headers:** +- Accept = application/json +- Content-Type = application/json +- Authorization = Bearer {SAT token} + +**Response Status:** 200 OK + +### Delete firmware rule template + +**POST** `http://:/firmwareruletemplate/testTemplateName` + +**Headers:** +- Content-Type = application/json +- Authorization = Bearer {SAT token} + +**Response Status:** 204 No Content + +--- + +## FirmwareRule + +### Retrieve all firmware rules + +**GET** `http://:/firmwarerule` + +**Headers:** +- Accept = application/json + +**Response Codes:** 200 + +### Retrieve filtered firmware rules + +**GET** `http://:/firmwarerule/filtered?templateId=TEST_ID&key=firmwareVersion` + +**Headers:** +- Accept = application/json +- Content-Type = application/json + +**Request Parameters:** +- `applicationType` (required): Filter by application type +- `name`: Filter templates by name +- `key`: Filter by rule key +- `value`: Filter by rule value +- `firmwareVersion`: Filter by firmware version +- `templateId`: Filter by template + +**Response Codes:** 200 + +### Import firmware rule + +**POST** `http://:/firmwarerule/importAll` + +**Headers:** +- Accept = application/json +- Content-Type = application/json + +**Request Body:** List of firmware rules + +**Response Codes:** 200, 400, 404, 409 + +**Response Body:** +```json +{ + "NOT_IMPORTED": [], + "IMPORTED": ["testName"] +} +``` + +### Create firmware rule + +**POST** `http://:/firmwarerule/?applicationType=stb` + +**Headers:** +- Accept = application/json +- Content-Type = application/json +- Authorization = Bearer {SAT token} + +**Response Status:** 201 Created + +### Update firmware rule + +**PUT** `http://:/firmwarerule/?applicationType=stb` + +**Headers:** +- Accept = application/json +- Content-Type = application/json +- Authorization = Bearer {SAT token} + +**Response Status:** 200 OK + +### Delete firmware rule + +**DELETE** `http://:/firmwarerule/2ea59bab-b080-4593-8539-fb6db5fc8fd5` + +**Headers:** +- Accept = application/json +- Content-Type = application/json +- Authorization = Bearer {SAT token} + +**Response Status:** 204 No Content + +--- + +## Feature + +### Retrieve all features + +**GET** `http://:/feature` + +**Headers:** +- Accept = application/json + +**Response Codes:** 200 + +### Retrieve filtered features + +**GET** `http://:/feature/filtered?` + +**Headers:** +- Accept = application/json +- Content-Type = application/json + +**Request Parameters:** +- `APPLICATION_TYPE` (required): Filter by application type +- `NAME`: Filter features by name +- `FEATURE_INSTANCE`: Filter by feature instance +- `FREE_ARG`: Filter by property key +- `FIXED_ARG`: Filter by property value + +**Response Codes:** 200 + +### Import feature + +**POST** `http://:/feature/importAll` + +**Headers:** +- Accept = application/json +- Content-Type = application/json + +**Request Body:** List of features + +**Response Codes:** 200, 400, 409 + +### Create feature + +**POST** `http://:/feature` + +**Headers:** +- Accept = application/json +- Content-Type = application/json + +**Response Codes:** 201, 400, 409 + +### Update feature + +**PUT** `http://:/feature` + +**Headers:** +- Accept = application/json +- Content-Type = application/json + +**Response Codes:** 201, 400, 404, 409 + +### Delete feature + +**DELETE** `http://:/feature/{id}` + +**Response Codes:** 204, 404, 409 + +--- + +## Feature Rule + +### Retrieve all feature rules + +**GET** `http://:/featurerule` + +**Headers:** +- Accept = application/json + +**Response Codes:** 200 + +### Retrieve filtered feature rules + +**GET** `http://:/featurerule/filtered?` + +**Headers:** +- Accept = application/json +- Content-Type = application/json + +**Request Parameters:** +- `APPLICATION_TYPE` (required): Filter by application type +- `NAME`: Filter by rule name +- `FREE_ARG`: Filter by feature rule key +- `FIXED_ARG`: Filter by feature rule value +- `FEATURE`: Filter by feature instance + +**Response Codes:** 200 + +### Import feature rule + +If feature rule with provided id does not exist it is imported otherwise updated. + +**POST** `http://:/featurerule/importAll` + +**Headers:** +- Accept = application/json +- Content-Type = application/json + +**Request Body:** List of feature rules + +**Response Codes:** 200, 400, 404, 409 + +### Create feature rule + +**POST** `http://:/featurerule` + +**Headers:** +- Accept = application/json +- Content-Type = application/json + +**Response Codes:** 201, 400, 404, 409 + +### Update feature rule + +**PUT** `http://:/featurerule` + +**Headers:** +- Accept = application/json +- Content-Type = application/json + +**Response Codes:** 201, 400, 404, 409 + +### Delete feature rule + +**DELETE** `http://:/featurerule/{id}` + +**Response Codes:** 204, 404, 409 + +--- + +## Activation Minimum Version + +### Retrieve all activation minimum versions + +**GET** `http://:/amv` + +**Headers:** +- Accept = application/json + +**Response Codes:** 200 + +### Retrieve filtered activation minimum versions + +**GET** `http://:/amv/filtered?` + +**Headers:** +- Accept = application/json +- Content-Type = application/json + +**Request Parameters:** +- `applicationType` (required): Filter by application type +- `DESCRIPTION`: Filter by description +- `MODEL`: Filter by model +- `PARTNER_ID`: Filter by partner id +- `FIRMWARE_VERSION`: Filter by firmware version +- `REGULAR_EXPRESSION`: Filter by regular expression + +**Response Codes:** 200 + +### Import activation version + +If activation minimum version with provided id does not exist it is imported otherwise updated. + +**POST** `http://:/amv/importAll` + +**Headers:** +- Accept = application/json +- Content-Type = application/json + +**Request Body:** List of activation minimum versions + +**Response Codes:** 200, 400, 404, 409 + +### Create activation minimum version + +**POST** `http://:/amv` + +**Headers:** +- Accept = application/json +- Content-Type = application/json + +**Response Codes:** 201, 400, 404, 409 + +### Update activation minimum version + +**PUT** `http://:/amv` + +**Headers:** +- Accept = application/json +- Content-Type = application/json + +**Response Codes:** 201, 400, 404, 409 + +### Delete activation minimum version + +**DELETE** `http://:/amv/{id}` + +**Response Codes:** 204, 404, 409 + +--- + +## Telemetry Profile + +### Retrieve all Telemetry Profiles + +**GET** `http://:/telemetry/profile` + +**Headers:** +- Accept = application/json +- Content-Type = application/json + +**Response Codes:** 200 + +### Retrieve Telemetry Profile + +**GET** `http://:/telemetry/profile/{id}` + +**Headers:** +- Accept = application/json +- Content-Type = application/json + +**Response Codes:** 200, 404 + +### Create Telemetry Profile + +**POST** `http://:/telemetry/profile` + +**Headers:** +- Accept = application/json +- Content-Type = application/json + +**Response Codes:** 201, 400, 409 + +### Update Telemetry Profile + +**PUT** `http://:/telemetry/profile` + +**Headers:** +- Accept = application/json +- Content-Type = application/json + +**Response Codes:** 200, 400, 404, 409 + +### Delete Telemetry Profile + +**DELETE** `http://:/telemetry/profile/{id}` + +**Headers:** +- Accept = application/json +- Content-Type = application/json + +**Response Codes:** 204, 404, 409 + +### Add Telemetry Profile Entry + +**PUT** `http://:/telemetry/profile/entry/add/{id}` + +**Headers:** +- Accept = application/json +- Content-Type = application/json + +**Response Codes:** 200, 404 + +### Remove Telemetry Profile entry + +**PUT** `http://:/telemetry/profile/entry/remove/{id}` + +**Headers:** +- Accept = application/json +- Content-Type = application/json + +**Response Codes:** 200, 404 + +### Create Telemetry Profile through pending changes + +**POST** `http://:/telemetry/profile/change` + +**Headers:** +- Accept = application/json +- Content-Type = application/json + +**Response Codes:** 201, 400, 409 + +### Update Telemetry Profile with approval + +**PUT** `http://:/telemetry/profile/change` + +**Headers:** +- Accept = application/json +- Content-Type = application/json + +**Response Codes:** 200, 400, 404, 409 + +### Delete Telemetry Profile with approval + +**DELETE** `http://:/telemetry/profile/change/{id}` + +**Headers:** +- Accept = application/json +- Content-Type = application/json + +**Response Codes:** 204, 404, 409 + +### Add Telemetry Profile Entry with approval + +**PUT** `http://:/telemetry/profile/change/entry/add/{id}` + +**Headers:** +- Accept = application/json +- Content-Type = application/json + +**Response Codes:** 200, 404 + +### Remove Telemetry Profile entry with approval + +**PUT** `http://:/telemetry/profile/change/entry/remove/{id}` + +**Headers:** +- Accept = application/json +- Content-Type = application/json + +**Response Codes:** 200, 404 + +--- + ## Telemetry Profile 2.0 ### Retrieve all Telemetry 2.0 Profiles From 9c53d8ca0d812fdc10ea1efe3e43f0e770a2e70d Mon Sep 17 00:00:00 2001 From: LakshmipriyaPurushan <60867402+LakshmipriyaPurushan@users.noreply.github.com> Date: Tue, 20 Jan 2026 14:40:01 +0530 Subject: [PATCH 14/23] Add files via upload --- docs/xconfadmin_API_Documentation_new.md | 7 +++++-- 1 file changed, 5 insertions(+), 2 deletions(-) diff --git a/docs/xconfadmin_API_Documentation_new.md b/docs/xconfadmin_API_Documentation_new.md index d7a80ec..81fd723 100644 --- a/docs/xconfadmin_API_Documentation_new.md +++ b/docs/xconfadmin_API_Documentation_new.md @@ -4,13 +4,13 @@ The XConf Admin API provides comprehensive configuration management for RDK devices through a RESTful interface. It manages firmware configurations, device settings, telemetry profiles, feature rules, and various configuration management operations. -**Base URL**: `https://:9443/xconfAdminService/` +**Base URL**: `/xconfAdminService` **Authentication**: Most endpoints require authentication via SAT token as a Bearer Token in the Authorization header. --- -## Table of Contents +## API Overview ### Configuration Management 1. [Firmware Config](#firmware-config) @@ -46,6 +46,9 @@ The XConf Admin API provides comprehensive configuration management for RDK devi 23. [Change API](#change-api) 24. [Change v2 API](#change-v2-api) +### Device Configuration Management +25. [DCM (Device Configuration Management)](#dcm-device-configuration-management) + --- ## Firmware Config From 27e45be3bbfc6a9d9edea1b2f4b29d76c089e018 Mon Sep 17 00:00:00 2001 From: LakshmipriyaPurushan <60867402+LakshmipriyaPurushan@users.noreply.github.com> Date: Tue, 20 Jan 2026 14:42:58 +0530 Subject: [PATCH 15/23] Add files via upload --- docs/xconfadmin_API_Documentation_new.md | 16 ++++++++-------- 1 file changed, 8 insertions(+), 8 deletions(-) diff --git a/docs/xconfadmin_API_Documentation_new.md b/docs/xconfadmin_API_Documentation_new.md index 81fd723..7e1db22 100644 --- a/docs/xconfadmin_API_Documentation_new.md +++ b/docs/xconfadmin_API_Documentation_new.md @@ -37,17 +37,17 @@ The XConf Admin API provides comprehensive configuration management for RDK devi 18. [Feature Rule](#feature-rule) 19. [Activation Minimum Version](#activation-minimum-version) +### Device Configuration Management +20. [DCM (Device Configuration Management)](#dcm-device-configuration-management) + ### Telemetry Management -20. [Telemetry Profile](#telemetry-profile) -21. [Telemetry Profile 2.0](#telemetry-profile-20) -22. [Telemetry 2.0 Profile Json Schema](#telemetry-20-profile-json-schema) +21. [Telemetry Profile](#telemetry-profile) +22. [Telemetry Profile 2.0](#telemetry-profile-20) +23. [Telemetry 2.0 Profile Json Schema](#telemetry-20-profile-json-schema) ### Change Management -23. [Change API](#change-api) -24. [Change v2 API](#change-v2-api) - -### Device Configuration Management -25. [DCM (Device Configuration Management)](#dcm-device-configuration-management) +24. [Change API](#change-api) +25. [Change v2 API](#change-v2-api) --- From 4b956070513aad80e245e199b5018cdf4175bdb0 Mon Sep 17 00:00:00 2001 From: LakshmipriyaPurushan <60867402+LakshmipriyaPurushan@users.noreply.github.com> Date: Tue, 20 Jan 2026 14:52:15 +0530 Subject: [PATCH 16/23] Add files via upload --- docs/xconfadmin_API_Documentation_new.md | 458 +++++++++++++++++++++++ 1 file changed, 458 insertions(+) diff --git a/docs/xconfadmin_API_Documentation_new.md b/docs/xconfadmin_API_Documentation_new.md index 7e1db22..b97de2d 100644 --- a/docs/xconfadmin_API_Documentation_new.md +++ b/docs/xconfadmin_API_Documentation_new.md @@ -2171,3 +2171,461 @@ PUT http://:/telemetry/v2/profile/change "author": "UNKNOWN_USER" } ``` + +--- + +## DCM (Device Configuration Management) + +### Retrieve all DCM Formulas + +Get all DCM formulas for authenticated application type: + +**GET** /dcm/formula?applicationType=stb + +**Headers:** +- Accept = application/json +- applicationType is not required, default value is stb + +**Response:** 200 OK + +**Response Body Example:** +`json +[ + { + "id": "formula-001", + "name": "STB Configuration Rule", + "description": "Configuration for STB devices", + "priority": 1, + "ruleExpression": "model == 'STB_MODEL_X'", + "percentage": 100, + "percentageL1": 50.0, + "percentageL2": 30.0, + "percentageL3": 20.0, + "applicationType": "stb", + "rule": { + "condition": { + "freeArg": "model", + "operation": "IS", + "fixedArg": "STB_MODEL_X" + } + } + } +] +` + +### Create DCM Formula + +Create a new DCM formula: + +**POST** /dcm/formula?applicationType=stb + +**Headers:** +- Content-Type = application/json +- Accept = application/json +- applicationType is not required, default value is stb + +**Response:** 201 CREATED; 400 BAD REQUEST; 500 INTERNAL SERVER ERROR + +**Request Body Example:** +`json +{ + "name": "New STB Configuration Rule", + "description": "New configuration for STB devices", + "priority": 2, + "ruleExpression": "model == 'STB_MODEL_Y'", + "percentage": 75, + "percentageL1": 40.0, + "percentageL2": 35.0, + "percentageL3": 25.0, + "applicationType": "stb", + "rule": { + "condition": { + "freeArg": "model", + "operation": "IS", + "fixedArg": "STB_MODEL_Y" + } + } +} +` + +**Response Body Example:** +`json +{ + "id": "formula-002", + "name": "New STB Configuration Rule", + "description": "New configuration for STB devices", + "priority": 2, + "ruleExpression": "model == 'STB_MODEL_Y'", + "percentage": 75, + "percentageL1": 40.0, + "percentageL2": 35.0, + "percentageL3": 25.0, + "applicationType": "stb", + "rule": { + "condition": { + "freeArg": "model", + "operation": "IS", + "fixedArg": "STB_MODEL_Y" + } + } +} +` + +### Retrieve all Device Settings + +Get all device settings: + +**GET** /dcm/deviceSettings + +**Headers:** +- Accept = application/json + +**Response:** 200 OK + +**Response Body Example:** +`json +[ + { + "id": "device-settings-001", + "name": "STB Device Settings", + "checkOnReboot": true, + "settingsAreActive": true, + "schedule": { + "type": "CronExpression", + "expression": "0 2 * * *", + "timeWindowMinutes": 60, + "startDate": "2025-01-01", + "endDate": "2025-12-31" + }, + "configData": { + "logLevel": "INFO", + "uploadOnReboot": true + } + } +] +` + +### Retrieve all Log Upload Settings + +Get all log upload settings: + +**GET** /dcm/logUploadSettings + +**Headers:** +- Accept = application/json + +**Response:** 200 OK + +**Response Body Example:** +`json +[ + { + "id": "log-upload-001", + "name": "Production Log Upload", + "uploadOnReboot": true, + "numberOfDays": 7, + "areSettingsActive": true, + "modeToGetLogFiles": "LogFiles", + "schedule": { + "type": "CronExpression", + "expression": "0 3 * * *", + "timeWindowMinutes": 120 + }, + "logFiles": [ + { + "name": "system.log", + "logFileName": "/var/log/system.log" + } + ], + "logUploadSettings": { + "uploadRepositoryName": "prod-repo", + "uploadProtocol": "HTTPS" + } + } +] +` + +### Retrieve all VOD Settings + +Get all Video On Demand settings: + +**GET** /dcm/vodsettings + +**Headers:** +- Accept = application/json + +**Response:** 200 OK + +**Response Body Example:** +`json +[ + { + "id": "vod-settings-001", + "name": "Production VOD Settings", + "locationsURL": "https://vod.example.com/locations", + "srmIPList": ["192.168.1.10", "192.168.1.11"], + "ipNames": ["SRM-1", "SRM-2"], + "ipList": ["192.168.1.10", "192.168.1.11"] + } +] +` + +### Retrieve all Upload Repositories + +Get all upload repository settings: + +**GET** /dcm/uploadRepository + +**Headers:** +- Accept = application/json + +**Response:** 200 OK + +**Response Body Example:** +`json +[ + { + "id": "repo-001", + "name": "Production Repository", + "description": "Production log upload repository", + "url": "https://logs.example.com/upload", + "protocol": "HTTPS", + "applicationType": "stb" + } +] +` +"@ | Add-Content "d:\RDKM\xconf_new_source_codes_generate_contents\xconfadmin_API_Documentation_new.md" +# First, remove any existing DCM section at the end + = Get-Content "d:\RDKM\xconf_new_source_codes_generate_contents\xconfadmin_API_Documentation_new.md" -Raw + = -replace '(?s)\n---\s*\n## DCM.*?$', '' + | Set-Content "d:\RDKM\xconf_new_source_codes_generate_contents\xconfadmin_API_Documentation_new.md" +"DCM section removed" + = Get-Content "d:\RDKM\xconf_new_source_codes_generate_contents\xconfadmin_API_Documentation_new.md" -Raw; = -replace '(?s)\n---\s*\n## DCM.*?$', ''; | Set-Content "d:\RDKM\xconf_new_source_codes_generate_contents\xconfadmin_API_Documentation_new.md"; "DCM section cleaned" +@" + +--- + +## DCM (Device Configuration Management) + +### Get All DCM Formulas +Get all DCM formulas for authenticated application type: + +**GET** \/dcm/formula?applicationType=stb\ + +
+Response Body: Array of DCM Formula objects + +\\\json +[ + { + "id": "formula-001", + "name": "STB Configuration Rule", + "description": "Configuration for STB devices", + "priority": 1, + "ruleExpression": "model == 'STB_MODEL_X'", + "percentage": 100, + "percentageL1": 50.0, + "percentageL2": 30.0, + "percentageL3": 20.0, + "applicationType": "stb", + "rule": { + "condition": { + "freeArg": "model", + "operation": "IS", + "fixedArg": "STB_MODEL_X" + } + } + } +] +\\\ +
+ +Response Codes: 200, 401 + +--- + +### Create DCM Formula +Create a new DCM formula: + +**POST** \/dcm/formula?applicationType=stb\ + +
+Request Body: DCM Formula creation data + +\\\json +{ + "name": "New STB Configuration Rule", + "description": "New configuration for STB devices", + "priority": 2, + "ruleExpression": "model == 'STB_MODEL_Y'", + "percentage": 75, + "percentageL1": 40.0, + "percentageL2": 35.0, + "percentageL3": 25.0, + "applicationType": "stb", + "rule": { + "condition": { + "freeArg": "model", + "operation": "IS", + "fixedArg": "STB_MODEL_Y" + } + } +} +\\\ +
+ +
+Response Body: Created DCM Formula object + +\\\json +{ + "id": "formula-002", + "name": "New STB Configuration Rule", + "description": "New configuration for STB devices", + "priority": 2, + "ruleExpression": "model == 'STB_MODEL_Y'", + "percentage": 75, + "percentageL1": 40.0, + "percentageL2": 35.0, + "percentageL3": 25.0, + "applicationType": "stb", + "rule": { + "condition": { + "freeArg": "model", + "operation": "IS", + "fixedArg": "STB_MODEL_Y" + } + } +} +\\\ +
+ +Response Codes: 201, 400, 401 + +--- + +### Get All Device Settings +Get all device settings: + +**GET** \/dcm/deviceSettings\ + +
+Response Body: Array of Device Settings objects + +\\\json +[ + { + "id": "device-settings-001", + "name": "STB Device Settings", + "checkOnReboot": true, + "settingsAreActive": true, + "schedule": { + "type": "CronExpression", + "expression": "0 2 * * *", + "timeWindowMinutes": 60, + "startDate": "2025-01-01", + "endDate": "2025-12-31" + }, + "configData": { + "logLevel": "INFO", + "uploadOnReboot": true + } + } +] +\\\ +
+ +Response Codes: 200, 401 + +--- + +### Get All Log Upload Settings +Get all log upload settings: + +**GET** \/dcm/logUploadSettings\ + +
+Response Body: Array of Log Upload Settings objects + +\\\json +[ + { + "id": "log-upload-001", + "name": "Production Log Upload", + "uploadOnReboot": true, + "numberOfDays": 7, + "areSettingsActive": true, + "modeToGetLogFiles": "LogFiles", + "schedule": { + "type": "CronExpression", + "expression": "0 3 * * *", + "timeWindowMinutes": 120 + }, + "logFiles": [ + { + "name": "system.log", + "logFileName": "/var/log/system.log" + } + ], + "logUploadSettings": { + "uploadRepositoryName": "prod-repo", + "uploadProtocol": "HTTPS" + } + } +] +\\\ +
+ +Response Codes: 200, 401 + +--- + +### Get All VOD Settings +Get all Video On Demand settings: + +**GET** \/dcm/vodsettings\ + +
+Response Body: Array of VOD Settings objects + +\\\json +[ + { + "id": "vod-settings-001", + "name": "Production VOD Settings", + "locationsURL": "https://vod.example.com/locations", + "srmIPList": ["192.168.1.10", "192.168.1.11"], + "ipNames": ["SRM-1", "SRM-2"], + "ipList": ["192.168.1.10", "192.168.1.11"] + } +] +\\\ +
+ +Response Codes: 200, 401 + +--- + +### Get All Upload Repositories +Get all upload repository settings: + +**GET** \/dcm/uploadRepository\ + +
+Response Body: Array of Upload Repository objects + +\\\json +[ + { + "id": "repo-001", + "name": "Production Repository", + "description": "Production log upload repository", + "url": "https://logs.example.com/upload", + "protocol": "HTTPS", + "applicationType": "stb" + } +] +\\\ +
+ +Response Codes: 200, 401 From 8de9d6fd57cac689a5f08faddbeb5fd11f91a1f3 Mon Sep 17 00:00:00 2001 From: LakshmipriyaPurushan <60867402+LakshmipriyaPurushan@users.noreply.github.com> Date: Tue, 20 Jan 2026 14:56:05 +0530 Subject: [PATCH 17/23] Add files via upload --- docs/xconfadmin_API_Documentation_new.md | 54 +----------------------- 1 file changed, 2 insertions(+), 52 deletions(-) diff --git a/docs/xconfadmin_API_Documentation_new.md b/docs/xconfadmin_API_Documentation_new.md index b97de2d..6e8655b 100644 --- a/docs/xconfadmin_API_Documentation_new.md +++ b/docs/xconfadmin_API_Documentation_new.md @@ -2393,62 +2393,11 @@ Get all upload repository settings: "applicationType": "stb" } ] -` -"@ | Add-Content "d:\RDKM\xconf_new_source_codes_generate_contents\xconfadmin_API_Documentation_new.md" -# First, remove any existing DCM section at the end - = Get-Content "d:\RDKM\xconf_new_source_codes_generate_contents\xconfadmin_API_Documentation_new.md" -Raw - = -replace '(?s)\n---\s*\n## DCM.*?$', '' - | Set-Content "d:\RDKM\xconf_new_source_codes_generate_contents\xconfadmin_API_Documentation_new.md" -"DCM section removed" - = Get-Content "d:\RDKM\xconf_new_source_codes_generate_contents\xconfadmin_API_Documentation_new.md" -Raw; = -replace '(?s)\n---\s*\n## DCM.*?$', ''; | Set-Content "d:\RDKM\xconf_new_source_codes_generate_contents\xconfadmin_API_Documentation_new.md"; "DCM section cleaned" -@" - ---- - -## DCM (Device Configuration Management) - -### Get All DCM Formulas -Get all DCM formulas for authenticated application type: - -**GET** \/dcm/formula?applicationType=stb\ - -
-Response Body: Array of DCM Formula objects - -\\\json -[ - { - "id": "formula-001", - "name": "STB Configuration Rule", - "description": "Configuration for STB devices", - "priority": 1, - "ruleExpression": "model == 'STB_MODEL_X'", - "percentage": 100, - "percentageL1": 50.0, - "percentageL2": 30.0, - "percentageL3": 20.0, - "applicationType": "stb", - "rule": { - "condition": { - "freeArg": "model", - "operation": "IS", - "fixedArg": "STB_MODEL_X" - } - } - } -] -\\\ +```
Response Codes: 200, 401 ---- - -### Create DCM Formula -Create a new DCM formula: - -**POST** \/dcm/formula?applicationType=stb\ -
Request Body: DCM Formula creation data @@ -2629,3 +2578,4 @@ Get all upload repository settings:
Response Codes: 200, 401 + From 1c33d3ffabaa92ca8043b8b779b16a172d63730c Mon Sep 17 00:00:00 2001 From: LakshmipriyaPurushan <60867402+LakshmipriyaPurushan@users.noreply.github.com> Date: Tue, 20 Jan 2026 15:01:55 +0530 Subject: [PATCH 18/23] Add files via upload --- docs/xconfadmin_API_Documentation_new.md | 240 ++++------------------- 1 file changed, 33 insertions(+), 207 deletions(-) diff --git a/docs/xconfadmin_API_Documentation_new.md b/docs/xconfadmin_API_Documentation_new.md index 6e8655b..20321b1 100644 --- a/docs/xconfadmin_API_Documentation_new.md +++ b/docs/xconfadmin_API_Documentation_new.md @@ -2176,20 +2176,16 @@ PUT http://:/telemetry/v2/profile/change ## DCM (Device Configuration Management) -### Retrieve all DCM Formulas +### Get All DCM Formulas Get all DCM formulas for authenticated application type: -**GET** /dcm/formula?applicationType=stb +**GET** `http://:/dcm/formula?applicationType=stb` -**Headers:** -- Accept = application/json -- applicationType is not required, default value is stb - -**Response:** 200 OK +
+Response Body: Array of DCM Formula objects -**Response Body Example:** -`json +```json [ { "id": "formula-001", @@ -2211,197 +2207,23 @@ Get all DCM formulas for authenticated application type: } } ] -` - -### Create DCM Formula - -Create a new DCM formula: - -**POST** /dcm/formula?applicationType=stb - -**Headers:** -- Content-Type = application/json -- Accept = application/json -- applicationType is not required, default value is stb - -**Response:** 201 CREATED; 400 BAD REQUEST; 500 INTERNAL SERVER ERROR - -**Request Body Example:** -`json -{ - "name": "New STB Configuration Rule", - "description": "New configuration for STB devices", - "priority": 2, - "ruleExpression": "model == 'STB_MODEL_Y'", - "percentage": 75, - "percentageL1": 40.0, - "percentageL2": 35.0, - "percentageL3": 25.0, - "applicationType": "stb", - "rule": { - "condition": { - "freeArg": "model", - "operation": "IS", - "fixedArg": "STB_MODEL_Y" - } - } -} -` - -**Response Body Example:** -`json -{ - "id": "formula-002", - "name": "New STB Configuration Rule", - "description": "New configuration for STB devices", - "priority": 2, - "ruleExpression": "model == 'STB_MODEL_Y'", - "percentage": 75, - "percentageL1": 40.0, - "percentageL2": 35.0, - "percentageL3": 25.0, - "applicationType": "stb", - "rule": { - "condition": { - "freeArg": "model", - "operation": "IS", - "fixedArg": "STB_MODEL_Y" - } - } -} -` - -### Retrieve all Device Settings - -Get all device settings: - -**GET** /dcm/deviceSettings - -**Headers:** -- Accept = application/json - -**Response:** 200 OK - -**Response Body Example:** -`json -[ - { - "id": "device-settings-001", - "name": "STB Device Settings", - "checkOnReboot": true, - "settingsAreActive": true, - "schedule": { - "type": "CronExpression", - "expression": "0 2 * * *", - "timeWindowMinutes": 60, - "startDate": "2025-01-01", - "endDate": "2025-12-31" - }, - "configData": { - "logLevel": "INFO", - "uploadOnReboot": true - } - } -] -` - -### Retrieve all Log Upload Settings - -Get all log upload settings: - -**GET** /dcm/logUploadSettings - -**Headers:** -- Accept = application/json - -**Response:** 200 OK - -**Response Body Example:** -`json -[ - { - "id": "log-upload-001", - "name": "Production Log Upload", - "uploadOnReboot": true, - "numberOfDays": 7, - "areSettingsActive": true, - "modeToGetLogFiles": "LogFiles", - "schedule": { - "type": "CronExpression", - "expression": "0 3 * * *", - "timeWindowMinutes": 120 - }, - "logFiles": [ - { - "name": "system.log", - "logFileName": "/var/log/system.log" - } - ], - "logUploadSettings": { - "uploadRepositoryName": "prod-repo", - "uploadProtocol": "HTTPS" - } - } -] -` - -### Retrieve all VOD Settings - -Get all Video On Demand settings: - -**GET** /dcm/vodsettings - -**Headers:** -- Accept = application/json - -**Response:** 200 OK - -**Response Body Example:** -`json -[ - { - "id": "vod-settings-001", - "name": "Production VOD Settings", - "locationsURL": "https://vod.example.com/locations", - "srmIPList": ["192.168.1.10", "192.168.1.11"], - "ipNames": ["SRM-1", "SRM-2"], - "ipList": ["192.168.1.10", "192.168.1.11"] - } -] -` - -### Retrieve all Upload Repositories - -Get all upload repository settings: +``` +
-**GET** /dcm/uploadRepository +Response Codes: 200, 401 -**Headers:** -- Accept = application/json +--- -**Response:** 200 OK +### Create DCM Formula -**Response Body Example:** -`json -[ - { - "id": "repo-001", - "name": "Production Repository", - "description": "Production log upload repository", - "url": "https://logs.example.com/upload", - "protocol": "HTTPS", - "applicationType": "stb" - } -] -``` - +Create a new DCM formula: -Response Codes: 200, 401 +**POST** `http://:/dcm/formula?applicationType=stb`
Request Body: DCM Formula creation data -\\\json +```json { "name": "New STB Configuration Rule", "description": "New configuration for STB devices", @@ -2420,13 +2242,13 @@ Response Codes: 200, 401 } } } -\\\ +```
Response Body: Created DCM Formula object -\\\json +```json { "id": "formula-002", "name": "New STB Configuration Rule", @@ -2446,7 +2268,7 @@ Response Codes: 200, 401 } } } -\\\ +```
Response Codes: 201, 400, 401 @@ -2454,14 +2276,15 @@ Response Codes: 201, 400, 401 --- ### Get All Device Settings + Get all device settings: -**GET** \/dcm/deviceSettings\ +**GET** `http://:/dcm/deviceSettings`
Response Body: Array of Device Settings objects -\\\json +```json [ { "id": "device-settings-001", @@ -2481,7 +2304,7 @@ Get all device settings: } } ] -\\\ +```
Response Codes: 200, 401 @@ -2489,14 +2312,15 @@ Response Codes: 200, 401 --- ### Get All Log Upload Settings + Get all log upload settings: -**GET** \/dcm/logUploadSettings\ +**GET** `http://:/dcm/logUploadSettings`
Response Body: Array of Log Upload Settings objects -\\\json +```json [ { "id": "log-upload-001", @@ -2522,7 +2346,7 @@ Get all log upload settings: } } ] -\\\ +```
Response Codes: 200, 401 @@ -2530,17 +2354,18 @@ Response Codes: 200, 401 --- ### Get All VOD Settings + Get all Video On Demand settings: -**GET** \/dcm/vodsettings\ +**GET** `http://:/dcm/vodsettings`
Response Body: Array of VOD Settings objects -\\\json +```json [ { - "id": "vod-settings-001", + "id": "vod-settings-001", "name": "Production VOD Settings", "locationsURL": "https://vod.example.com/locations", "srmIPList": ["192.168.1.10", "192.168.1.11"], @@ -2548,7 +2373,7 @@ Get all Video On Demand settings: "ipList": ["192.168.1.10", "192.168.1.11"] } ] -\\\ +```
Response Codes: 200, 401 @@ -2556,14 +2381,15 @@ Response Codes: 200, 401 --- ### Get All Upload Repositories + Get all upload repository settings: -**GET** \/dcm/uploadRepository\ +**GET** `http://:/dcm/uploadRepository`
Response Body: Array of Upload Repository objects -\\\json +```json [ { "id": "repo-001", @@ -2574,7 +2400,7 @@ Get all upload repository settings: "applicationType": "stb" } ] -\\\ +```
Response Codes: 200, 401 From e452d3948e9a2b6af67024b41bbc1f8b2d26a100 Mon Sep 17 00:00:00 2001 From: LakshmipriyaPurushan <60867402+LakshmipriyaPurushan@users.noreply.github.com> Date: Tue, 20 Jan 2026 15:16:52 +0530 Subject: [PATCH 19/23] Add files via upload --- docs/xconfadmin_API_Documentation_new.md | 22 ++++++++-------------- 1 file changed, 8 insertions(+), 14 deletions(-) diff --git a/docs/xconfadmin_API_Documentation_new.md b/docs/xconfadmin_API_Documentation_new.md index 20321b1..0c5b04b 100644 --- a/docs/xconfadmin_API_Documentation_new.md +++ b/docs/xconfadmin_API_Documentation_new.md @@ -6,8 +6,6 @@ The XConf Admin API provides comprehensive configuration management for RDK devi **Base URL**: `/xconfAdminService` -**Authentication**: Most endpoints require authentication via SAT token as a Bearer Token in the Authorization header. - --- ## API Overview @@ -2085,26 +2083,22 @@ If activation minimum version with provided id does not exist it is imported oth --- -## Change v2 API - -### Approve by change ids (not supported in golang implementation) +## Telemetry 2.0 Profile Json Schema -All not selected changes by entity id will be canceled. For example, there are two changes, "change A" and "change B", id of "change A" is sent to approve, in result "change A" will be approved and "change B" will be canceled. +The JSON schema definition for Telemetry 2.0 profiles allows you to validate and define the structure of telemetry configuration data. -**POST** `http://:/change/v2/approve/byChangeIds` +**GET** `http://:/telemetry/v2/jsonschema` **Headers:** - Accept = application/json -- Content-Type = application/json -**Request Body:** Array with change ids -```json -["4705486f-2dcc-4ae9-a920-a45b33755993"] -``` +**Response Codes:** 200 -**Response Codes:** 200, 404, 409 +**Response Body:** JSON Schema object defining the structure for Telemetry 2.0 profiles -**Response Body:** Change id - error message object. If change successfully approve an empty object is returned +--- + +## Change v2 API ### Approve by entity id (not supported in golang implementation) From d2d051358c0e77024a5e13f4fd40442bee852c3c Mon Sep 17 00:00:00 2001 From: LakshmipriyaPurushan <60867402+LakshmipriyaPurushan@users.noreply.github.com> Date: Tue, 20 Jan 2026 15:27:34 +0530 Subject: [PATCH 20/23] Add files via upload --- docs/xconfadmin_API_Documentation_new.md | 11 ++--------- 1 file changed, 2 insertions(+), 9 deletions(-) diff --git a/docs/xconfadmin_API_Documentation_new.md b/docs/xconfadmin_API_Documentation_new.md index 0c5b04b..0e844ba 100644 --- a/docs/xconfadmin_API_Documentation_new.md +++ b/docs/xconfadmin_API_Documentation_new.md @@ -2085,16 +2085,9 @@ If activation minimum version with provided id does not exist it is imported oth ## Telemetry 2.0 Profile Json Schema -The JSON schema definition for Telemetry 2.0 profiles allows you to validate and define the structure of telemetry configuration data. +The JsonConfig field of a Telemetry 2.0 Profile is validated using the following JSON Schema, which defines the structure and validation rules for the JSON configuration sent to RDK devices. -**GET** `http://:/telemetry/v2/jsonschema` - -**Headers:** -- Accept = application/json - -**Response Codes:** 200 - -**Response Body:** JSON Schema object defining the structure for Telemetry 2.0 profiles +**File Reference:** `telemetry_profile_2_0_schema.json` --- From d90f273e7442fd7b2f8dd5f1eee8c9858cc4210b Mon Sep 17 00:00:00 2001 From: LakshmipriyaPurushan <60867402+LakshmipriyaPurushan@users.noreply.github.com> Date: Tue, 20 Jan 2026 15:30:05 +0530 Subject: [PATCH 21/23] Add files via upload From ea8c4243e87fc095a82cd8cbe9d37376de9b4015 Mon Sep 17 00:00:00 2001 From: LakshmipriyaPurushan <60867402+LakshmipriyaPurushan@users.noreply.github.com> Date: Tue, 20 Jan 2026 15:34:49 +0530 Subject: [PATCH 22/23] Add files via upload --- docs/xconfadmin_API_Documentation_new.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/xconfadmin_API_Documentation_new.md b/docs/xconfadmin_API_Documentation_new.md index 0e844ba..a5a6f56 100644 --- a/docs/xconfadmin_API_Documentation_new.md +++ b/docs/xconfadmin_API_Documentation_new.md @@ -2087,7 +2087,7 @@ If activation minimum version with provided id does not exist it is imported oth The JsonConfig field of a Telemetry 2.0 Profile is validated using the following JSON Schema, which defines the structure and validation rules for the JSON configuration sent to RDK devices. -**File Reference:** `telemetry_profile_2_0_schema.json` +**File Reference:** [telemetry_profile_2_0_schema.json](https://github.com/rdkcentral/telemetry/blob/main/schemas/t2_reportProfileSchema.schema.json) --- From 7706cd064cbe3eec9a2d2a83f379215556d514a4 Mon Sep 17 00:00:00 2001 From: LakshmipriyaPurushan <60867402+LakshmipriyaPurushan@users.noreply.github.com> Date: Tue, 20 Jan 2026 15:37:11 +0530 Subject: [PATCH 23/23] Add files via upload --- docs/xconfadmin_API_Documentation_new.md | 10 ---------- 1 file changed, 10 deletions(-) diff --git a/docs/xconfadmin_API_Documentation_new.md b/docs/xconfadmin_API_Documentation_new.md index a5a6f56..0155fcc 100644 --- a/docs/xconfadmin_API_Documentation_new.md +++ b/docs/xconfadmin_API_Documentation_new.md @@ -2093,16 +2093,6 @@ The JsonConfig field of a Telemetry 2.0 Profile is validated using the following ## Change v2 API -### Approve by entity id (not supported in golang implementation) - -To approve all changes by entity id - -**GET** `http://:/change/v2/approve/byEntityId/{id}` - -**Response Codes:** 200, 404, 409 - -**Response Body:** Change id - error message object. If change successfully approve an empty object is returned - ### Cancel change **GET** `http://:/change/v2/cancel/{changeId}`