legacy-api-modernization

name	legacy-api-modernization
enabled	true
description	Use when performing legacy api modernization — guides the modernization of legacy APIs (SOAP, XML-RPC, proprietary protocols) to modern RESTful or GraphQL interfaces. Covers API discovery, contract analysis, versioning strategy, backward compatibility, consumer migration, and deprecation planning.
required_connections	[{"prefix":"api-gateway","label":"API Gateway"}]
config_fields	[{"key":"legacy_api_type","label":"Legacy API Type","required":true,"placeholder":"e.g., SOAP, XML-RPC, proprietary REST"},{"key":"target_api_style","label":"Target API Style","required":true,"placeholder":"e.g., REST, GraphQL, gRPC"},{"key":"consumer_count","label":"Number of API Consumers","required":false,"placeholder":"e.g., 15"}]
features	["CLOUD_MIGRATION","API","MODERNIZATION"]

Legacy API Modernization Plan

Phase 1: API Discovery & Analysis

1. Catalog all legacy API endpoints
   • Endpoint URLs and methods
   • Request/response schemas (WSDL, XSD, etc.)
   • Authentication mechanisms
   • Rate limits and SLAs
   • Error handling patterns
2. Identify all API consumers and their usage patterns
3. Document business logic embedded in API layer
4. Measure current traffic volumes and latency baselines

Consumer Impact Matrix

Consumer	Endpoints Used	Traffic Volume	Migration Difficulty	Priority
		req/day	Low/Med/High	1-5

Phase 2: Modern API Design

1. Design resource-oriented API structure (REST) or schema (GraphQL)
2. Define OpenAPI / GraphQL schema specification
3. Plan versioning strategy (URL path, header, query param)
4. Design authentication flow (OAuth 2.0, API keys, JWT)
5. Define rate limiting and throttling policies
6. Plan pagination, filtering, and sorting patterns

Endpoint Mapping

Legacy Endpoint	Modern Endpoint	Method	Breaking Change	Adapter Needed
			Yes/No	Yes/No

Phase 3: Adapter Layer Implementation

1. Build adapter/facade layer between legacy and modern APIs
2. Implement request/response transformation logic
3. Handle data format conversion (XML to JSON, etc.)
4. Maintain backward compatibility through the adapter
5. Add comprehensive logging for both old and new paths

Phase 4: Modern API Implementation

1. Implement modern API endpoints
2. Write comprehensive API tests (unit, integration, contract)
3. Set up API documentation (Swagger UI, GraphQL Playground)
4. Configure API gateway routing
5. Implement monitoring and alerting

Phase 5: Consumer Migration

1. Publish migration guide and updated SDK/client libraries
2. Provide sandbox environment for consumer testing
3. Migrate consumers in waves, starting with internal teams
4. Monitor error rates per consumer during migration
5. Provide support window for each migration wave

Phase 6: Deprecation & Decommission

1. Announce deprecation timeline for legacy endpoints
2. Add deprecation headers to legacy API responses
3. Monitor remaining legacy traffic
4. Remove adapter layer after all consumers migrated
5. Decommission legacy API infrastructure

Counter-Rationalizations

Shortcut	Counter	Why
"We can skip some steps for this case"	Adapt the workflow steps, don't skip them	Skipped steps are where incidents and oversights originate
"The user seems to already know what to do"	Complete all workflow phases with the user	The workflow catches blind spots that experience alone misses
"This is a minor case, full process is overkill"	Scale the process down, don't turn it off	Minor cases become major when unstructured; the process scales, not disappears
"I'll fill in the details later"	Complete each section before moving on	Deferred details are forgotten; real-time capture is more accurate
"The template output isn't necessary"	Always produce the structured output format	Structured output enables comparison, audit trails, and handoff to other teams

Output Format

• API Inventory: Complete catalog of legacy endpoints and consumers
• Modern API Specification: OpenAPI/GraphQL schema document
• Migration Guide: Consumer-facing documentation for migration
• Adapter Architecture: Design for backward-compatible transition
• Deprecation Timeline: Phased schedule with milestones

Action Items

• Complete legacy API discovery and consumer mapping
• Design and review modern API specification
• Build adapter layer with backward compatibility
• Deploy modern API to staging for consumer testing
• Migrate consumers in planned waves
• Enforce deprecation dates and decommission legacy API