Plan

0001: Simple XML Response Adapter Implementation Plan

Reference

• Specification: /home/coder/src/workspaces/codev/codev/specs/0001-simple-xml-response.md
• Source Design: /home/coder/src/workspaces/codev/repos/domain-apis/.kiro/specs/simple-xml-response-adapter/design.md
• Repository: repos/domain-apis

Current State Analysis

The following components are already implemented:

1. Adapter Registry (gateway/lambda/src/adapters/registry.ts)

   • AdapterRegistry class with register(), get(), getAll() methods
   • Adapter, ServiceConfig, RelationshipConfig, TransformResult interfaces
   • Global adapterRegistry singleton

2. SimpleXmlResponseAdapter (gateway/lambda/src/adapters/simple-xml-response/index.ts)

   • transformResponse() - XML to JSON transformation with header update
   • injectLinks() - Link injection based on service config

3. XML Transformer (gateway/lambda/src/adapters/simple-xml-response/transformer.ts)

   • transformToJson() - Uses fast-xml-parser
   • transformToXml() - Reverse transformation
   • normalizeCollection() - Collection normalization helper

4. Link Injector (gateway/lambda/src/adapters/simple-xml-response/link-injector.ts)

   • injectLinksFromConfig() - Adds _links section with self and relationship links
   • constructUrl() - URL pattern substitution

5. Service Config Loader (gateway/lambda/src/config/service-config.ts)

   • loadServiceConfig() - Loads and validates service.yaml files
   • Config caching for performance

6. Gateway Integration (gateway/lambda/src/index.ts)

   • initializeAdapters() - Registers SimpleXmlResponseAdapter on cold start
   • detectAdapter() - Extracts API name, loads config, checks for adapters
   • Response transformation for XML content-type responses
   • Error handling with 502 responses for transformation failures

What remains:

• Payment API service configuration (specs/payment/service.yaml)
• Mock backend returning XML responses
• Integration tests for full gateway flow with XML backend
• Include parameter support with XML-backed resources
• Acceptance tests for end-to-end scenarios

---

Phase 1: Payment API Service Configuration

Objective: Create the service configuration file that declares the Payment API uses the simple-xml-response adapter.

Tasks

1.1. Create specs/payment/service.yaml with adapter and relationship configuration:

• Declare adapters: [simple-xml-response]
• Define taxpayer relationship (links to Taxpayer API)
• Define allocations relationship (links to Payment API allocations)

Files to Create

File	Purpose
specs/payment/service.yaml	Payment API adapter and relationship config

Success Criteria

• loadServiceConfig('payment') returns valid ServiceConfig object
• config.adapters includes 'simple-xml-response'
• config.relationships.taxpayer has all required fields
• config.relationships.allocations uses custom urlPattern
• Unit test verifies config loading for payment API

Dependencies

• None (first phase)

---

Phase 2: XML Mock Backend Setup

Objective: Configure the Payment API mock to return XML responses for testing.

Tasks

2.1. Create XML response examples in the Payment API OpenAPI spec:

• Add application/xml response content type to /payments/{id} endpoint
• Add XML example matching the JSON schema structure

2.2. Create Prism mock configuration or custom mock server:

• Option A: Configure Prism to return XML when Accept: application/xml is sent
• Option B: Create a simple Express server that returns XML for testing

2.3. Update docker-compose.yml to include XML mock backend if needed

Files to Modify

File	Change
specs/payment/payment-api.yaml	Add XML response content types and examples
docker-compose.yml	Add XML mock backend service (if needed)

Files to Create

File	Purpose
tests/mocks/payment-xml-mock.ts	XML mock server for testing (if Prism doesn’t support XML)

Success Criteria

• Mock backend responds with XML when appropriate headers sent
• XML structure matches expected payment resource format
• Gateway can fetch from XML mock backend

Dependencies

• Phase 1 (service config must exist for adapter detection)

---

Phase 3: Gateway Integration Tests

Objective: Verify the gateway correctly transforms XML responses from backends.

Tasks

3.1. Add integration tests for adapter detection with Payment API:

• Test detectAdapter('/payment/payments/PM001') returns correct context
• Test adapter is correctly identified from service config

3.2. Add integration tests for XML response transformation:

• Mock fetch to return XML with Content-Type: application/xml
• Verify response is transformed to JSON
• Verify Content-Type header is updated to application/json

3.3. Add integration tests for link injection:

• Verify _links.self is correctly constructed
• Verify _links.taxpayer points to taxpayer API
• Verify _links.allocations uses custom URL pattern

3.4. Add integration tests for error scenarios:

• Invalid XML from backend returns 502 with TRANSFORMATION_ERROR
• Missing required fields for link injection handled gracefully

Files to Modify

File	Change
gateway/lambda/src/index.test.ts	Add XML transformation integration tests

Files to Create

File	Purpose
gateway/lambda/src/index.xml-integration.test.ts	Dedicated XML integration test suite

Success Criteria

• All new integration tests pass
• Tests cover happy path (XML → JSON transformation)
• Tests cover error path (invalid XML handling)
• Tests verify link injection with relationships
• Existing tests continue to pass

Dependencies

• Phase 1 (service config for adapter detection)

---

Phase 4: Include Parameter Support for XML Resources

Objective: Enable the include query parameter to work with XML-backed resources.

Tasks

4.1. Verify current include parameter flow handles transformed resources:

• The gateway already fetches related resources from _links
• After XML transformation, _links are injected
• Verify included resource fetching works with injected links

4.2. Add integration test for include with XML primary resource:

• Request /payment/payments/PM001?include=taxpayer
• Verify primary resource transformed from XML
• Verify taxpayer fetched and included in response

4.3. Add integration test for include traversing from JSON to XML:

• Request /taxpayer/taxpayers/TP123?include=payments
• Taxpayer API returns JSON (no adapter)
• Payments link fetched from XML backend
• Verify payments transformed and included

Files to Modify

File	Change
gateway/lambda/src/index.xml-integration.test.ts	Add include parameter tests

Success Criteria

• Include parameter works with XML primary resource
• Include parameter works when following links to XML backend
• Included resources have correct _links sections
• Multiple includes work simultaneously

Dependencies

• Phase 3 (basic XML transformation must work)

---

Phase 5: Acceptance Tests

Objective: Verify end-to-end functionality through acceptance tests that exercise the full system.

Tasks

5.1. Create acceptance test for single Payment resource:

• GET /payment/payments/PM20230001
• Backend returns XML
• Response is JSON with _links.self, _links.taxpayer, _links.allocations
• Validate against OpenAPI schema

5.2. Create acceptance test for Payment collection:

• GET /payment/payments
• Backend returns XML collection
• Response is JSON with items array
• Each item has _links section

5.3. Create acceptance test for cross-API traversal:

• GET /taxpayer/taxpayers/TP123456?include=payments
• Taxpayer from JSON backend
• Payments from XML backend
• Payments correctly included and transformed

5.4. Create acceptance test for include with XML primary:

• GET /payment/payments/PM20230001?include=taxpayer
• Payment from XML backend (transformed)
• Taxpayer from JSON backend
• Both resources in response with correct structure

Files to Create

File	Purpose
tests/acceptance/xml-adapter.acceptance.test.ts	End-to-end XML adapter tests

Success Criteria

• All acceptance tests pass against running services
• Tests can be run with task test:acceptance or similar
• Tests document expected behavior for XML backends
• Tests serve as living documentation

Dependencies

• Phase 2 (XML mock backend must be available)
• Phase 3 (integration tests validate individual components)
• Phase 4 (include parameter support verified)

---

Implementation Order Summary

Phase 1: Payment API Service Configuration
    |
    v
Phase 2: XML Mock Backend Setup
    |
    v
Phase 3: Gateway Integration Tests
    |
    v
Phase 4: Include Parameter Support
    |
    v
Phase 5: Acceptance Tests

Each phase produces a committable unit of work with its own success criteria. Phases can be reviewed independently.

Out of Scope (Deferred to Future Work)

Per the specification, these items are explicitly not included:

• Property-based tests (tasks 2.5, 3.4, 4.5, 5.3, 5.4, 6.3, 6.4, 8.5-8.9)
• Error handling refinements (Phase 7 tasks from original breakdown)
• Documentation and cleanup (Phase 9 tasks from original breakdown)
• Request transformation (JSON to XML for request bodies)
• Response caching optimizations
• SOAP protocol support