Architecture work for a large insurance enterprise. The client, its partners and the third-party providers are not named, and the details are generalised. This page describes the target architecture and the approach, not a finished migration and not measured results.
The problem
Critical business services were running on legacy integration middleware, with the business logic buried inside the integration flows and the middleware's own database holding business and process data. That makes the logic hard to find, hard to test, hard to change and tied to one product's lifecycle. The goal was to move that logic into services the business can own, behind a modern API layer, without breaking the partners and applications that depend on it today.
The target architecture
Services are organised around business domains (party and customer, policy administration, claims, billing and payments, product and coverage, documents, reinsurance, accounting, reporting and analytics, and so on). Each domain service owns its own data, with the datastore chosen per domain (relational where transactions matter, document or cache where the access pattern fits). Services publish and consume events on the event platform instead of calling each other for everything.
The gateway does not implement business logic
The most important rule in this design is what Apigee is not allowed to do. The gateway handles the cross-cutting concerns:
- Security: authentication and authorisation, rate limiting and threat protection, with a web application firewall on the external edge.
- An anti-corruption layer: it shields the services from the shape and the changes of the outside world, and the outside world from the internals.
- Bounded-context mapping: it translates an incoming request into the domain's own data model, so the boundary between the gateway and the business logic stays clear.
Business processing is delegated to the domain services. This keeps the gateway thin and fast to change, makes the logic testable in ordinary code, and avoids the situation this project set out to fix: logic hidden inside the integration product. There are two gateways, one for internal consumers and one for external partners, so each has its own policies, quotas and exposure.
Moving logic out of the legacy flows
Lifting every flow into the gateway would only move the problem. The approach is a structured assessment first:
Three practices matter:
- Assess before you migrate. Identify the stored procedures, automated jobs and manual jobs (including scheduled cron tasks) that sit around the flows. They are part of the behaviour, and they are the usual source of surprises.
- Do not move logic to the gateway without a logic assessment. Anything that is more than security, routing or mapping belongs in a domain service.
- Migrate by consumer, with the old path still running. Compare results, then retire the legacy flow.
A gated process for new APIs
A platform with a gateway needs a process, or the gateway becomes a free-for-all. The API lifecycle is a sequence of gates owned by different roles: product and business owners, an API centre of excellence, the backend teams, API governance, security and IT operations.
Each phase has a decision point and a defined hand-off. Security and data-privacy checks happen at feasibility, not after the build. A governance check against the standards happens before production. Operations feeds capacity planning back into the process.
Design decisions worth copying
- A thin gateway, a thick domain. Gateways are for cross-cutting concerns. Logic lives in services.
- One owner per domain. Each service owns its data and its API, and teams can deploy independently.
- Datastore per domain ("polyglot persistence"). Choose the store for the access pattern, not for uniformity.
- Separate internal and external gateways. Different audiences, different policies.
- Events for cross-domain reactions. Calls are for questions, events are for facts.
- Governance as a process, not a document. Gates, owners and checks that actually run.
Trade-offs
- More services to run. Smaller services reduce code duplication and ease maintenance, but they need CI/CD, monitoring and on-call ownership.
- Distributed data. Moving from one middleware database to per-domain stores means no cross-database transactions. Use sagas and idempotent events where consistency spans domains.
- Migration risk. The longer both paths run, the more they can diverge. Set a cut-over plan and an end date.
- Governance overhead. Gates slow down trivial changes. Right-size the process by the risk of the API.