Replace your legacy APIs without breaking the integrations that depend on them.

Every day your team spends writing SOAP XML envelopes is a day not spent on the features your business needs.

Legacy APIs created in the SOAP era, proprietary RPC frameworks and monolith-embedded service interfaces create significant friction: WSDL-generated client code that is verbose and fragile, XML parsing overhead that modern JSON avoids, SOAP faults that provide less information than HTTP status codes, and WS-* security standards replaced by OAuth 2.0 and JWT. Modernising these APIs improves developer productivity, enables modern tooling and reduces integration friction for partners. The engineering challenge: do it without breaking the hundreds of integrations that depend on the current interface.

The API modernisation process.

System Layers

• Assessment Layer: API inventory, consumer mapping, dependency analysis, breaking change identification
• Design Layer: Modern API design, OpenAPI specification, versioning strategy, migration path
• Facade Layer: Translation proxy, format conversion (XML/JSON), protocol adapter, legacy compatibility
• Migration Layer: Consumer migration support, documentation, SDKs, migration tooling
• Cutover Layer: Traffic monitoring, deprecation timeline, legacy sunset, support period

Core Technical Capabilities

• SOAP to REST Migration

  WSDL analysis, REST resource design from SOAP operations, XML to JSON transformation, SOAP fault to HTTP status code mapping, WS-Security to OAuth 2.0 migration.

• API Facade / Adapter

  Facade layer that exposes modern REST API while translating to legacy backend — allows new consumers to use REST while existing SOAP consumers continue unmodified. Temporary compatibility bridge during migration.

• Versioning & Backwards Compatibility

  Semantic versioning strategy, non-breaking change identification (additive only: new fields, new endpoints), breaking change management via versioning, deprecation headers and sunset timeline.

• OpenAPI-first Design

  OpenAPI 3.1 specification for all modernised APIs — designed before implementation, reviewed as API contract, used to generate documentation and client SDKs.

• Consumer Migration Support

  Migration guides per consumer type, code samples in multiple languages, SDK generation, migration testing environment and dedicated support period for consuming teams.

• API Gateway Migration

  Migration from legacy API management (IBM DataPower, Axway, layer7) to modern API gateway (Kong, AWS API Gateway, Apigee) with policy migration, rate limiting and monitoring.

How we think about API modernisation.

API modernisation is constrained by the existing consumers. The most elegantly designed modern API is useless if it breaks all existing integrations.

• Facade first, rewrite second

  The facade pattern allows deploying a modern API interface immediately — the facade translates to the legacy backend. Consumers can migrate to the new interface at their own pace. The legacy backend is then replaced incrementally behind the facade without any consumer impact. This is the safest migration path: consumers see one API that evolves.

  Axiom:

• Breaking changes require a major version

  Adding new optional fields, new endpoints, new enum values, new optional request parameters — these are non-breaking changes that can be deployed without incrementing the API version. Removing fields, changing field types, removing endpoints, making optional fields required — these are breaking changes that require a new major version and a deprecation period for the old version.

  Axiom:

• Consumer impact analysis precedes API design

  Before designing the new API, map every consumer: who are they, what operations do they use, what response fields do they actually consume (not just what the API returns), and what are their migration timelines. This analysis changes the design: fields that some consumers depend on cannot be removed in v1.

  Axiom:

• Documentation and SDKs are migration accelerators

  The main friction in consumer migration is developer time to understand the new API and update their integration. High-quality migration guides with before/after examples, working code samples in the consumer's language, and auto-generated SDKs reduce migration time per consumer from weeks to days.

  Axiom:

API modernisation decisions.

• Facade vs direct rewrite?

  Impact: Facade + incremental backend rewrite for SOAP-to-REST where consumers are external or have long change cycles. Direct migration with versioned coexistence for internal APIs with fast-moving consumer teams.

  • Facade first, rewrite backend later — lowest risk, consumers unaffected
  • Full rewrite with versioned coexistence — v1 and v2 live simultaneously
  • Direct migration with consumer coordination — fastest, highest coordination cost
  • Strangler fig per endpoint — granular, long migration period

• Versioning approach for modern API?

  Impact: URL versioning for public and partner APIs — universally understood, easy to test in browser, clear in logs. Agree on the strategy before building v1.

  • URL versioning (/v1/, /v2/) — explicit, easy to test, recommended
  • Header versioning (API-Version) — cleaner URLs, harder to browse
  • Date-based versioning (2024-01-01) — fine-grained, Stripe style
  • No versioning — only for internal APIs with colocated consumers

• SOAP XML handling?

  Impact: Custom parser for complex SOAP payloads — gives full control over mapping logic and error handling. Apache Camel for integration platforms where SOAP is one of many legacy protocols.

  • XSLT transformation — mature, XPath-based, verbose for complex mappings
  • Custom parser (Java/Python) — flexible, requires maintenance
  • Apache Camel — integration framework, good for SOAP/REST routing
  • WS-to-REST gateway (MuleSoft, IBM) — managed, expensive

• Authentication migration?

  Impact: OAuth 2.0 client credentials for server-to-server REST APIs. Separate auth migration from API migration where possible — changing auth and API format simultaneously increases migration complexity.

  • WS-Security to OAuth 2.0 — industry standard for REST
  • API keys — simpler than OAuth, sufficient for server-to-server
  • Mutual TLS (mTLS) — client certificate auth, some financial services requirement
  • Passthrough (same auth as legacy) — no migration during API migration

• Legacy API sunset timeline?

  Impact: 12-month deprecation period for external partner APIs — gives consumers adequate time. 6 months for internal APIs where migration can be coordinated. Hard sunset date prevents indefinite legacy maintenance.

  • Immediate shutdown after new version — high consumer risk
  • 6-month deprecation period — minimum reasonable
  • 12-month deprecation period — standard for partner-facing APIs
  • No sunset — maintain indefinitely (accumulating cost)

• Consumer migration tooling?

  Impact: Migration SDK for large consumer bases — a thin wrapper that implements the old interface signatures internally but calls the new API. Consumers update one dependency version and their code continues to work.

  • No tooling — consumers migrate manually
  • Migration guide only — documentation, no automation
  • Code migration scripts (codemods) — automated client code updates
  • Migration SDK — wrapper around old interface that calls new API

What PROPELOO modernises.

• SOAP to REST Migration

  WSDL analysis, REST resource design, XML-to-JSON facade, OAuth 2.0 migration and consumer migration guide.

• Monolith API Extraction

  Extract embedded service interfaces from monolith to standalone REST APIs with OpenAPI documentation and versioning.

• API Gateway Migration

  Migrate from legacy API management platform to Kong or AWS API Gateway — policy migration, rate limiting parity, monitoring equivalence.

• Internal API Standardisation

  Standardise inconsistent internal APIs to OpenAPI spec, consistent error format, unified authentication and developer documentation.

• Partner API Programme

  Transform internal service APIs into a documented partner API programme with sandbox, developer portal, rate limiting tiers and SLA.

• Legacy System API Layer

  Add modern REST API layer to legacy mainframe or ERP system — consumer abstraction while the backend remains unchanged.

The API modernisation stack.

• Legacy

  Stack: WSDL/SOAP analysis, Apache Axis, IBM DataPower, MuleSoft (existing)

• Modern API

  Stack: Node.js (Fastify), Go, Python (FastAPI), OpenAPI 3.1, gRPC

• Facade & Gateway

  Stack: Kong API Gateway, AWS API Gateway, Apache Camel, Custom Node.js proxy

• Documentation

  Stack: Stoplight, Redoc, Scalar, Swagger UI, openapi-generator

• Testing

  Stack: Postman (contract tests), Pact (consumer-driven), k6 (load testing), SoapUI (legacy validation)

• Monitoring

  Stack: Datadog APM, AWS API Gateway metrics, Custom migration progress dashboard

API modernisation must maintain security posture.

• Authentication equivalence

  New API authentication (OAuth 2.0) must provide at least the same security guarantees as the legacy mechanism (WS-Security). Validate that new auth cannot be bypassed.

• Authorisation parity

  Every authorisation check in the legacy API must have an equivalent in the modern API. Missing authorisation on any endpoint is a security regression.

• Facade security

  The facade layer inherits the attack surface of both the modern API it exposes and the legacy system it connects to. Input validation at the facade, authentication on both the facade and legacy backend, and no passing of unvalidated input from facade to legacy.

• Migration period risks

  During the migration period, both old and new APIs are live. Ensure the same security monitoring covers both, and that security incidents in the legacy system do not affect the modern API.

• Breaking change documentation

  Security-relevant breaking changes (authentication method, authorisation model, rate limiting) must be clearly documented in the migration guide and communicated to consumers before the change is deployed.

• Token migration

  If migrating from API key to OAuth 2.0, plan the token migration: provision OAuth clients for all existing API key consumers, allow a dual-support period and set a hard cutover date.

From legacy API to modern platform.

1. 01. API & Consumer Inventory

   Map all legacy API endpoints, consumers, usage patterns and data contracts.

2. 02. Modern API Design

   OpenAPI spec, versioning strategy, authentication design, breaking change analysis.

3. 03. Facade Implementation

   Translation layer: legacy protocol to modern REST/JSON, authentication bridge.

4. 04. Developer Experience

   Documentation, SDKs, migration guide, sandbox environment.

5. 05. Consumer Migration

   Support consumers in migrating to new API, migration SDK if needed.

6. 06. Monitoring & Cutover

   Traffic monitoring, deprecation headers, sunset date enforcement.

7. 07. Legacy Decommission

   Confirm all consumers migrated, sunset legacy API, decommission infrastructure.

Frequently Asked Questions