Adding an API layer to a legacy monolith

An API layer for a legacy system is a thin, well-documented service that sits in front of the old code and exposes what it can do as clean endpoints. The legacy system keeps running exactly as it did; the difference is that everything new, whether a mobile app, a partner, a reporting tool or an AI agent, talks to the façade rather than to the database or the screens. That single change is what turns "we cannot touch it" into "we can replace it one piece at a time". This article covers how to build the façade, what to expose first, how to keep it from becoming a second monolith, and what it costs.

Why an API façade is the first modernisation step

Most legacy monoliths are integrated by the worst possible means: other systems read its database tables directly, scrape its screens, or exchange files on a schedule. Every one of those couplings makes the monolith harder to change, because a schema tweak breaks a downstream report nobody remembered. An API façade replaces those couplings with a contract. Once callers depend on the contract rather than the internals, the internals can be refactored, upgraded or replaced behind it without anyone noticing. It is also the fastest way to get value: the moment a capability has an endpoint, a copilot or a partner can use it, months before any replacement is finished.

Ways to expose a legacy system as an API

Designing the API layer

Model the business, not the tables

The façade's endpoints should be named for what the business does: create an order, publish results, schedule a delivery, retrieve a customer's statement. They should not mirror the legacy schema. Mirroring the schema leaks the very structure you are trying to hide, and the first replacement of a module then breaks every caller. Spend the first week with the people who run the business, listing the capabilities they need from outside the system, and shape the contract around that list.

Version from the first release

Put a version in the path or the header on day one. Callers will depend on the contract, and you will want to change it as the monolith's quirks are cleaned up. A versioned API can carry an old contract for a while and retire it on a date; an unversioned one traps you in the first design.

Handle reads and writes differently

Reads are safe to serve straight from the legacy database through a read model, and that is where most early value lives: reporting, search, copilots, partner lookups. Writes must go through the legacy business logic, because a decade of validation rules lives there and bypassing it corrupts data in ways that surface at month end. The façade can call the legacy application's own entry points, a queued job the old system processes, or an in-process adapter. It should never write to the tables directly until that module has been replaced.

Map errors honestly

Legacy systems fail in odd ways: an HTML error page, a silent zero, a partial write. The façade's job is to turn those into structured, documented error responses, and to be idempotent on writes so that a retry does not create a duplicate order. This mapping is the least glamorous part of the work and the part that decides whether partners and agents can rely on the API.

Keeping the façade from becoming a second monolith

• Keep business logic out of the façade; it routes, translates and validates shape, nothing more
• One module boundary per API domain, so each can be re-pointed at a replacement independently
• Contract tests on every endpoint so a replacement is proven to match before the switch
• Authentication, rate limiting and audit logging at the gateway, not inside each endpoint
• Usage metrics per endpoint and per caller, which become the map for the replacement sequence

That last point deserves emphasis. The façade's logs tell you which capabilities matter, to whom, and how often. When the time comes to choose the first module to replace under a strangler pattern, that evidence beats any opinion.

What the API layer makes possible immediately

The same week an endpoint goes live, it can be used. A field app can submit jobs. A partner can check stock. A document-extraction pipeline can post structured data into the system instead of someone re-keying it. A copilot can answer "what is the status of this customer's order" from a read model with permission checks at the gateway. Each of those is a piece of the legacy-to-AI modernization path, and none of them requires the monolith to change. We describe the AI half of this in embedding AI into legacy systems without a rewrite. Because AI agents call tools through the same contract, the API layer is also where policy gates and audit trails live, and it is worth designing it with the OWASP API security guidance open from the start.

A worked example

A last-mile logistics operator ran dispatch on a monolith that its customers integrated with by emailing spreadsheets, which an operator re-keyed. A façade was built in front of it: read endpoints for shipment status served from a replicated read model, and a create-shipment endpoint that queued jobs into the legacy application's own import path so its validation rules still applied. Within weeks the largest customers were submitting shipments directly, a driver app consumed the status endpoint, and the re-keying stopped. The endpoint logs then showed which parts of the monolith carried the load, which set the order for replacing them. The dispatch platform case study describes what followed.

Team and timeline

A first façade covering the highest-value read and write capabilities is typically an architect, two backend engineers and a QA engineer for six to ten weeks, with a client-side domain owner who can explain what each capability really does and a database administrator who knows the schema's history. Where the goal is integration alone, it is scoped under API development and integrations from $7,000 / ₹4.4L; where it is the first step of a replacement, it opens a ReCore programme from $31,500 / ₹22,40,000, with the ranges on the pricing page. You own the contract, the code and the documentation, and the façade runs under a Care Plan once partners depend on it.

Before you start: a checklist

• A list of every system that currently reads the legacy database or scrapes its screens
• The business capabilities needed from outside, named in business language
• A decision per capability: read model, legacy entry point or queued job
• A versioning scheme and a deprecation policy written before the first endpoint ships
• Gateway-level authentication, rate limits and audit logging
• Contract tests for each endpoint that a replacement must also pass
• Idempotency keys on every write endpoint
• Endpoint and caller usage metrics from the first day

Glossary

• Façade: a service that presents a clean interface in front of a more complex or older system
• Read model: a copy of legacy data shaped for queries, kept in sync by replication or change capture
• Contract test: a test that checks an endpoint's behaviour against its published specification
• Idempotency: a repeated request with the same key has the same effect as one request
• Change-data-capture: streaming database changes as events for other systems to consume
• Gateway: the entry point that handles authentication, limits and logging for all endpoints

Questions clients ask

• Should the façade be REST or GraphQL? REST with clear resources is enough for almost every legacy case; GraphQL adds value only when many callers need very different shapes of the same data.
• Can the vendor of the legacy system object? Check the licence. Reading your own database is normally fine; automating a vendor's UI may not be.
• What if the monolith has no callable entry points for writes? Queue a job into its own import path, or add a minimal in-process adapter; do not write to the tables directly.
• Will the façade slow things down? A read model is usually faster than the legacy screens; writes add a few milliseconds of translation, which callers do not notice.
• Who maintains the API documentation? It is generated from the contract in the pipeline, so it cannot drift from the code.

Related reading

See API-first SaaS for contract design, MCP explained for how agents consume the same endpoints, and copilot actions through your existing API for the permission model.

Put a contract in front of the monolith, route reads and writes with care, and every later decision about replacement becomes one you can make module by module.