Standards Alignment
Extensible API design aligned with AWS API standards for long-term maintainability
HCX API Design Collaboration
This project demonstrates upstream product influence during EVS HCX feature API design. As a documentation lead participating in API design reviews, I identified opportunities to align with parallel VPC development work, raised considerations regarding long-term maintainability, and advocated for alignment with AWS API design standards. These discussions influenced the team’s decision to adopt an extensible architecture that supports current needs while enabling future capabilities.
The Challenge
Section titled “The Challenge”Balancing Speed and Extensibility
Section titled “Balancing Speed and Extensibility”During EVS planning, the team designed a new API capability for the HCX public connectivity feature. This feature enables VMware workload migrations for customers without dedicated private connections—removing a significant cost barrier that limited EVS adoption. Because EVS is fundamentally a migration service and HCX is the primary migration tool, this feature was strategically important for broadening EVS’s customer base.
The feature required associating elastic IP addresses to HCX appliances. Elastic IPs provide the stable, persistent public addresses necessary for reliable HCX communication over the internet. Dynamic IP addresses that change with instance reboots would break migration connections, making elastic IPs essential for this architecture.
Initial architectural discussions focused on a single-purpose API design scoped specifically to the HCX feature. This reflected delivery timeline priorities. However, identifying synergies with parallel VPC development initiatives presented an opportunity to align the HCX API design with broader platform patterns. AWS API design standards emphasize extensible architectures from v1 because public APIs must maintain backward compatibility indefinitely—they can never be removed once shipped. Surfacing this context created an opportunity to align the HCX API design with these long-term maintainability principles.
As the documentation lead participating in API design reviews, I recognized several concerns:
Backward Compatibility Risks:
- Single-purpose API design would limit future extensibility
- Adding capabilities later would require breaking changes or additional APIs
- Risk of API proliferation as EVS evolved
Standards Alignment:
- AWS API design standards emphasize extensible, flexible architectures
- Single-purpose designs create maintenance burden over time
- Customer experience suffers when APIs require frequent versioning
Cross-Service Integration Opportunity:
- Parallel VPC development work could reduce EVS implementation overhead
- Coordination between teams could prevent duplicate effort
- Leveraging existing patterns would improve consistency
Strategic Influence
Section titled “Strategic Influence”Advocating for Extensible Architecture
Section titled “Advocating for Extensible Architecture”Building Cross-Functional Collaboration:
Early in the development cycle, I established regular syncs with EVS PMs and engineers and integrated documentation into engineering workflows using shared project management tools. These collaboration mechanisms created visibility into upcoming architectural decisions and positioned me to contribute meaningfully during HCX API design discussions.
Cross-Team Coordination:
During these design discussions, I surfaced the parallel VPC development work to EVS product and engineering teams, demonstrating how leveraging existing AWS infrastructure patterns could reduce implementation complexity while improving long-term maintainability.
Standards-Based Advocacy:
Rather than prescribing specific solutions, I framed the discussion around AWS API design standards and customer experience principles. I walked through trade-offs:
- Speed vs. Sustainability: Single-purpose design ships faster but creates technical debt
- Flexibility vs. Simplicity: Extensible architecture requires more upfront planning but enables future capabilities
- Alignment vs. Independence: Leveraging AWS patterns improves consistency but requires cross-team coordination
Customer Experience Focus:
I emphasized the downstream customer impact of architectural decisions. APIs that require frequent versioning or accumulate redundant operations create confusion and integration complexity for customers building on EVS.
Impact
Section titled “Impact”Extensible Architecture Adopted
Section titled “Extensible Architecture Adopted”Architectural Evolution:
EVS product and engineering teams adopted an extensible API design that supports current HCX requirements while enabling future capabilities. The team shifted from single-purpose design considerations to an extensible architecture aligned with AWS API standards. This approach supports elastic IP association for HCX while providing flexibility for future use cases without requiring breaking changes.
Benefits:
For Customers:
- Consistent API patterns aligned with AWS standards
- Future-proof design reduces integration churn
- Clearer mental model for API capabilities
For EVS:
- Reduced long-term maintenance burden
- Flexibility to add capabilities without API proliferation
- Improved alignment with AWS service integration patterns
For Cross-Team Collaboration:
- VPC terminology consistency addressed across EVS and VPC documentation
- Coordinated approach reduced duplicate effort
- Established pattern for future cross-service features
Feature Launch Success:
The HCX public connectivity feature launched in Q3 2025, enabling VMware migrations for customers without costly Direct Connect connections. The extensible API design supports current needs while preventing future breaking changes for customers building EVS integrations. Documentation launched simultaneously across all surfaces, reflecting the architectural flexibility in clear, maintainable content.
Future-Proof Architecture
Flexible design supports current + future use cases without breaking changes
Cross-Service Consistency
Coordinated VPC terminology and patterns across EVS documentation
Successful Launch
Feature launched Q3 2025 expanding EVS adoption to customers requiring public HCX connectivity for workload migrations
Key Takeaways
Section titled “Key Takeaways”Customer Experience Advocates Can Influence Technical Architecture
Section titled “Customer Experience Advocates Can Influence Technical Architecture”Documentation teams have unique visibility into how customers interact with APIs. This customer-facing perspective creates valuable input for architectural decisions that might not be immediately obvious from implementation timelines.
Standards Alignment Requires Balanced Trade-Off Discussions
Section titled “Standards Alignment Requires Balanced Trade-Off Discussions”AWS API design standards protect long-term customer experience, but delivery timelines create legitimate tension. Documentation teams bring customer-facing perspective to architectural discussions, helping ensure both immediate delivery needs and long-term maintainability considerations inform design decisions.
Cross-Service Awareness Creates Opportunities
Section titled “Cross-Service Awareness Creates Opportunities”Understanding parallel development work across AWS services enables identification of opportunities to reduce complexity and improve consistency. This systems-level thinking adds value beyond traditional documentation scope.