How do you build a custom API for a legacy system?

A custom API can use an adapter to bridge old and new data models. It maps requests so the old model does not limit new service design.1
Microsoft calls this an anti-corruption layer, a bridge between systems with different data meanings.1 Its guidance covers input checks and logs where those systems have different trust levels.2
How does a custom API wrap a legacy system?
Microsoft's Azure example splits the client-facing API from the work of changing data shapes. Azure API Management checks access, limits traffic, and provides a REST facade.2
In that example, Azure Functions maps a REST order message to a domain model. It then maps that model to a legacy data transfer object.2
For your design, treat a data transfer object as an agreed message shape. Define the public request, then map its fields to the old system's input. Keep that mapping separate from the API's access checks.
Which patterns bridge modern clients and old backends?
A gateway can handle shared tasks such as access checks and traffic limits. It can also translate protocols on behalf of backend services. Microsoft says never to move business logic into that gateway.3
Use the gateway for access checks and the adapter for your data mappings. Before choosing SOAP or direct database access, get the old system's supported interface contract. For database access, ask its owner to approve reads, writes, and transaction rules.
The layer can use an event-driven approach instead of a request and immediate reply. Microsoft names Azure Service Bus, Azure Event Grid, and Azure Event Hubs as options. This message-based approach separates the new domain from the old system's throughput limits.2
Choose request-response when your needs call for a result in the same exchange. Consider the message-based option when the caller can wait for the work to finish. Specify how that caller will check the result before you approve the design.
What would a hypothetical JSON-to-SOAP ERP adapter do?
Hypothetical worked example: suppose a web app must send orders to a SOAP-based ERP. Treat the ERP as the company's existing order system for this example. The contract below is an invented design, not a tested link to a product.
How would the hypothetical request become an ERP order?
For this hypothetical contract, let the client send POST /orders with the JSON below. Require a customer ID, a product code, and a positive whole-number quantity. Assign a tracking ID to the request before passing it to the adapter.
{
"customerId": "C104",
"items": [
{"productCode": "P7", "quantity": 2}
]
}
In this hypothetical adapter, first check the required fields and reject unknown fields. Next, build an internal order using the approved customer and product mappings. Then map that order to the ERP's invented CreateSalesOrder operation.
For this example, map customerId to AccountCode and each item to an OrderLine. Map productCode to StockCode, and quantity to Units. Build the SOAP request from the real ERP contract, not these invented names.
How would the hypothetical response and errors reach the client?
Suppose the hypothetical ERP returns order number SO9001 and result code OK. Have the adapter map that reply to the JSON response below. Keep the invented ERP field names out of the public contract.
{
"orderId": "SO9001",
"status": "accepted",
"requestId": "req-104"
}
For this hypothetical contract, map an unknown customer to HTTP 422 and code CUSTOMER_NOT_FOUND. Map an ERP timeout to HTTP 504 and code ERP_TIMEOUT. Keep the tracking ID in the client reply and the internal error record.
In this design, do not treat a timeout as proof that the order failed. Require an order-status check before allowing another submission after an uncertain result. Agree on that recovery rule with the ERP owner before you build the adapter.
How should the boundary handle security and overload?
A gateway can manage client-facing certificates and handle TLS termination for backend services. It can also check who calls, monitor traffic, translate protocols, and throttle requests.3 For your design, spell out where the secure client connection ends.
Microsoft advises making backends accept requests only through the intended gateway path. Direct access can bypass the gateway's access checks, traffic limits, request checks, and logs.3
Systems on each side of the adapter may have different trust levels. Microsoft advises considering checks and cleanup of input at this boundary. It also calls for tracking IDs and structured logs to trace mapping failures.2
The layer can itself become a single point of failure. Microsoft names Retry, Circuit Breaker, Bulkhead, and Health Endpoint Monitoring as resilience patterns.2
Before release, ask for clear retry rules and thresholds for halting failed calls. Specify limits that isolate work, plus checks of the layer's health. Require the ERP owner's input before setting traffic limits or retrying writes.
Test those choices against the agreed backend capacity and recovery rules. Treat caching and modern access tokens as separate design choices, not assumed wrapper features.
For any proposed cache, specify which data may be reused and for how long. For tokens, require a documented method to check them and enforce access rules. Name who holds credentials, where checks run, and how old credentials will be retired.
When should you choose a wrapper instead of replacing the core?
An adapter keeps the old domain model from limiting a new service's design.1 Use that boundary benefit as one part of your decision, not a savings forecast.
Martin Fowler gives reduced risk as the main reason to consider a strangler fig approach. He compares this step-by-step approach with a cut-over rewrite. Frequent releases can give value steadily and make progress easier to track.4
Favor a wrapper proposal when your immediate goal is a clearly bounded link. Ask whether the approved interface supports the needed fields, workload, and recovery rules. Request a replacement proposal too when that interface cannot meet your needs.
For the cost comparison, price both paths over the same planning period. Include adapter upkeep, gateway running costs, testing, and legacy support in the wrapper estimate. Include moving data, changing workflows, testing, and cut-over work in the replacement estimate.
Do not approve the wrapper just because its first release looks cheaper. Ask each proposal to state its assumptions, long-term owner, and exit plan. Weigh those answers against your interface needs and the risk you can accept.