0001: Simple XML Response Adapter Implementation

Summary

Implement an adapter to transform XML backend responses to JSON for the domain API gateway, enabling legacy XML-based backend services to participate in the unified API architecture while maintaining a consistent JSON interface for clients.

Problem Statement

Some HODs (Heads of Duty) with legacy systems cannot provide modern REST APIs with JSON responses and HATEOAS-compliant hypermedia links. Currently, these systems are excluded from the domain API architecture, requiring clients to implement separate integration patterns for XML-based services. This fragmentation increases client complexity, reduces discoverability, and prevents unified API governance.

The gateway needs the ability to:

Accept XML responses from legacy backends
Transform them to JSON matching the OpenAPI Specification (OAS)
Inject hypermedia links that XML backends cannot provide
Support the include parameter for resource embedding

Goals

Complete SimpleXmlResponseAdapter implementation - Finalize the adapter class with full transformResponse and injectLinks functionality
Gateway integration - Wire the adapter into the gateway request/response flow with proper detection and invocation
Payment API configuration - Create a reference implementation using the Payment API as an XML backend example
Include parameter support - Enable the include parameter to work seamlessly with XML-backed resources
Acceptance test coverage - Verify end-to-end functionality across all key scenarios

Non-Goals

Request transformation (JSON to XML) - The simple-xml-response adapter only handles response transformation; backends are expected to accept standard GET requests with inputs passed via URL
SOAP protocol support - SOAP adapters would be a separate implementation
Field mapping/renaming - Transformation preserves XML field names as-is
Response caching - Caching optimizations are deferred to future work
Custom type coercion beyond standard XML parsing behavior
Property-based tests for advanced validation (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)
Documentation and cleanup (Phase 9 tasks)

Technical Approach

Architecture

The adapter follows the Strategy Pattern with an Adapter Registry:

Client (JSON) -> Gateway -> Adapter Detection -> Backend (XML)
                    |
                    v
             transformResponse() -> injectLinks() -> Client (JSON)

Key Components

SimpleXmlResponseAdapter (gateway/lambda/src/adapters/simple-xml-response/index.ts)
- Implements the Adapter interface
- transformResponse(): Converts XML to JSON, updates Content-Type header
- injectLinks(): Adds _links section based on service configuration
Service Configuration (specs/{api-name}/service.yaml)
- Declares which adapters an API requires
- Defines relationship mappings for link injection
Gateway Integration (gateway/lambda/src/index.ts)
- Detect adapter requirements from service config
- Apply transformation in response flow
- Handle include parameter with XML resources

Implementation Tasks (H-Priority)

Phase 3: Adapter Implementation

3.1: Implement SimpleXmlResponseAdapter class (partially complete, needs finalization)
3.2: Register SimpleXmlResponseAdapter in gateway initialization

Phase 4: Gateway Integration

4.1: Add detectAdapter() function to gateway request handler
4.2: Integrate adapter in backend request flow (headers for XML backends)
4.3: Integrate adapter in backend response flow (transformResponse + injectLinks)
4.4: Integration tests for gateway adapter flow

Phase 5: Payment API Configuration

5.1: Create specs/payment/service.yaml with adapter and relationship config
5.2: Update Payment API mock backend to return XML responses

Phase 6: Include Parameter Support

6.2: Integration tests for include parameter with XML backends

Phase 8: Acceptance Testing

8.1: Acceptance test for Payment API with XML backend
8.2: Acceptance test for cross-API traversal (JSON → XML)
8.3: Acceptance test for include parameter with XML
8.4: Acceptance test for collection endpoints

Service Configuration Format

adapters:
  - simple-xml-response
 
relationships:
  taxpayer:
    targetApi: taxpayer
    targetResource: taxpayers
    sourceField: taxpayerId
    linkType: taxpayer
    linkTitle: "Taxpayer who made this payment"
  allocations:
    targetApi: payment
    targetResource: allocations
    sourceField: id
    urlPattern: "/payments/{id}/allocations"
    linkType: collection
    linkTitle: "Allocations for this payment"

Success Criteria

Functional
- XML backend responses are correctly transformed to JSON
- Transformed responses validate against OAS schemas
- _links sections contain self link plus all configured relationships
- Include parameter works with XML-backed resources
- Cross-API traversal works seamlessly (JSON API → XML API)
Behavioral Parity
- Clients cannot distinguish XML-backed from JSON-backed APIs
- All existing gateway tests pass unchanged
- Response structure is identical regardless of backend type
Test Coverage
- Integration tests cover adapter detection, transformation, and link injection
- Acceptance tests verify end-to-end scenarios
- Payment API serves as working reference implementation

Dependencies

Existing Infrastructure (Complete)
- Adapter registry and interface (gateway/lambda/src/adapters/registry.ts)
- Service configuration loader (gateway/lambda/src/config/service-config.ts)
- XML transformer (gateway/lambda/src/adapters/simple-xml-response/transformer.ts)
- Link injector (gateway/lambda/src/adapters/simple-xml-response/link-injector.ts)
External Libraries
- fast-xml-parser - XML parsing (already in dependencies)
- js-yaml - YAML parsing for service config (already in dependencies)
Runtime Environment
- AWS Lambda with Node.js runtime
- API Gateway for routing

Risks

Risk	Impact	Mitigation
XML parsing edge cases	Medium	Comprehensive unit tests cover nested objects, arrays, special characters, empty values
Performance overhead	Low	~5-15ms transformation overhead is acceptable; monitor in production
Service config errors	Medium	Validate configs at load time; fail fast with descriptive errors
Include parameter complexity	Medium	Reuse existing include logic; only add XML transformation layer
Link URL construction errors	Medium	Unit tests for URL pattern substitution; validate field existence

References

Source requirements: /home/coder/src/workspaces/codev/repos/domain-apis/.kiro/specs/simple-xml-response-adapter/requirements.md
Design document: /home/coder/src/workspaces/codev/repos/domain-apis/.kiro/specs/simple-xml-response-adapter/design.md
Task breakdown: /home/coder/src/workspaces/codev/repos/domain-apis/.kiro/specs/simple-xml-response-adapter/tasks.md
Existing adapter code: /home/coder/src/workspaces/codev/repos/domain-apis/gateway/lambda/src/adapters/simple-xml-response/

Techcle Wiki

Explorer

Spec