White paper — Microservices & APIs: modern architectures for agility

White paper · April 2026

Microservices & APIs: modern architectures for agility

Cut right, contract well, operate calmly

“The goal was never to have microservices. The goal is to deliver independently — microservices are only one means to that end, and not always the right one.”

1 question

6 contracts

90 days

before cutting anything: “who must be able to deliver without asking permission?”

The API rules that hold an ecosystem together: design, versioning, data, errors, security, lifecycle

The action plan, from the domain map to the first extracted service in production

This white paper draws on the architecture engagements of the Clarendis network; it complements “DevOps at Scale”, whose foundations it shares.

Contents

Foreword 03 Executive summary — the document in ten statements 04 Your reading path 06 1 The microservices misunderstanding The goal is independent delivery · What the field evidence says · The monolith is not the enemy · The three-conditions test 07 2 The foundations: domains and boundaries Cut along the business, never the technology · Bounded contexts · The domain map · Boundaries and Conway's law 13 3 The API as a contract Design first · The six contracts · Versioning without breaking · REST, events, or both · Lightweight governance 19 4 Architecture in practice Synchronous or asynchronous · Each service owns its data · Resilience by design · The front end facing the constellation 25 5 Operating the constellation The gateway and the mesh · Distributed observability · Progressive deployment · What the platform must provide 31 6 The blind spots The distributed monolith · Transactions that cross boundaries · The constellation's costs · Security between services · The five-questions test 37 7 The 90-day action plan Where are you starting from? · D1-D30: the domain map · D31-D60: the contract and the first extraction · D61-D90: in production, measured · The five-number dashboard 43 Moving to execution 49 Appendices — Glossary, references, about Clarendis 50

Foreword

Ten years after the wave, microservices have produced two populations of organisations: those that deliver faster than before, and those that traded a comprehensible monolith for an incomprehensible constellation — slower, more expensive, more fragile. The difference between the two comes down neither to talent nor to tooling: it comes down to the order of decisions. The first cut their business domain, then contracted their interfaces, then tooled their operations. The second started with the technology.

This white paper follows the right order. Boundaries first (chapter 2): you do not cut a system, you cut a business. Contracts next (chapter 3): an API is not plumbing, it is a promise others depend on. Architecture and operations then (chapters 4-5), and the blind spots the conference talks leave out (chapter 6).

A point of intellectual honesty: we sell no API platform, no cloud, no packaged software — and we do not believe microservices are the right default answer. Part of our engagements consists precisely in advising against the split, or in limiting it. Chapter 1 owns that position, references in hand.

How to read this document. The chapters stand alone. If the “should we split?” debate is raging in your organisation, chapter 1 will settle it with three verifiable conditions. If the split is agreed but the boundaries are disputed, chapter 2 is your method. If your APIs are multiplying without rules, chapter 3 is your governance. Each chapter closes with the same panel, what this changes for you, written for three readers: the chief executive, the CIO, the architect. Deliberately the same subject seen from three angles — because these architectures fail wherever strategy, budget and design stop talking to each other.

Enjoy the read — and may your boundaries hold.

Cédric Guittard

Anna Hoang

cedric.guittard@clarendis.com

anna.hoang@clarendis.com

for the Clarendis team

Executive summary

The document in ten statements. Each is developed in the chapter indicated.

1

2

Microservices are a means, never an end. The end is independent delivery: each team able to deploy without asking permission. If you get it with a modular monolith, you have won — more simply. (Chapter 1)

Three conditions before cutting: stable business boundaries, an operations platform that holds the road, and teams able to own their services in production. One missing? The split waits. (Chapter 1)

3

4

You cut a business, not a system. The right boundaries are the domain's bounded contexts — where the vocabulary changes meaning. A technical boundary (the “PDF service”) manufactures coupling; a business boundary eliminates it. (Chapter 2)

An API is a contract, not plumbing. It is designed before it is coded (design first), versioned without breaking its consumers, and managed as a product — with its users, its documentation and its lifecycle. (Chapter 3)

5

6

Winning API governance is lightweight and tooled : few rules, checked automatically in the pipeline, a living catalogue — not an architecture committee re-reading PDFs. (Chapter 3)

Asynchronous is the real decoupling. Two services calling each other synchronously fall together. Events decouple their fates — at the price of deferred consistency, which must be owned business case by business case. (Chapter 4)

7

8

Each service owns its data — no exceptions. The shared database is the hardest coupling there is: it turns the constellation into a distributed monolith. Data travels through contracts, never through direct access. (Chapter 4)

A constellation is not operated like a monolith. Gateway, distributed observability with tracing, progressive deployment: this foundation is not optional — it is the price of entry, and it is provided by the platform, not reinvented by each team. (Chapter 5)

9

10

The distributed monolith is the worst of both worlds. Services that deploy together, call each other in cascades and share their data carry all the costs of microservices and none of the benefits. Chapter 6 gives the tests to detect it. (Chapter 6)

You migrate by strangling, never by big bang. The first service is extracted from the monolith in 90 days, in production, measured — and each subsequent extraction is justified by the flow, not by architectural purity. (Chapter 7)

Where to start, depending on your situation:

The monolith is slowing you down, the debate is raging. Chapter 1 (the three conditions), then chapter 2: the domain map will settle it better than opinions.

The services exist, the APIs are proliferating without rules. Chapter 3 in full — the six contracts and lightweight governance — then §6.1 to check you have not built a distributed monolith.

The constellation is expensive and breaks often. Chapters 5 and 6: the operating foundation and the blind spots — then chapter 7's dashboard to put numbers on what comes next.

Your reading path

Three marked itineraries. The “What this changes for you” panels, at the end of each chapter, are written for your seat.

CEO Chief executive 20 minutes

CIO CIO / CTO 1 h 30

ARC Architect 2 hours

Full document recommended. Your critical path:

You design the boundaries. Your path:

01 Executive summary

02 chapter 1 (the three conditions — and the cost of a premature split)

01 chapter 1 (the decision framework, to adopt as is)

01 chapter 2 in full (bounded contexts, the domain map)

02 chapter 2 (the domain map: the workshop to organise)

02 chapter 3 (the six contracts, versioning)

03 chapter 6, §6.3 (what a constellation really costs)

03 chapter 5 (the foundation your platform must provide)

03 chapter 4 (sync/async, data, resilience)

04 chapter 7, §7.4 (the five numbers to put on your agenda).

04 the seven “Architect” panels, at the end of each chapter.

04 chapter 6 (costs, security, the distributed monolith)

You will know when to say yes, when to say no, and how to verify.

05 chapter 7 in full — the plan is yours.

What you came looking for

Need

Where

In what form

Settling the “should we split?” debate

Chapter 1

Three verifiable conditions, and the modular-monolith alternative, owned

A method for cutting

Chapter 2

Bounded contexts without the jargon, and the one-day “domain map” workshop

API rules that hold

Chapter 3

The six contracts, versioning without breakage, lightweight tooled governance

A plan executable tomorrow

Chapter 7

90 days in three movements, the first extraction in production, five steering numbers

Chapter 1

The microservices misunderstanding

1

Before cutting anything, you must know why you are cutting — and accept that the honest answer is sometimes: you don't.

1.1 The goal is independent delivery

The word “microservices” describes a shape — small services deployed separately — and the shape ended up masking the function. The function, the only one that justifies the cost, fits in one sentence: allow each team to deliver its part without coordinating, without waiting, without asking permission. It is an organisational property before it is a technical one — independent delivery, the very thing the lead time of our “DevOps at Scale” white paper measures.

This reformulation changes everything, because it makes the goal reachable by several roads. A well-modularised monolith, with clean internal boundaries and fast deployment, delivers a large share of independent delivery — with no network between modules, no distributed consistency, no constellation to operate. Microservices add only one thing: independence of deployment and of scaling. If you do not need that precise thing, you do not need their costs.

The governance question is therefore never “should we do microservices?” but: “who, in our organisation, must be able to deliver without asking permission — and what stops them today?” If the answer is “the code's boundaries”, chapter 2 concerns you. If the answer is “the approvals and the environments”, it is a DevOps problem, and the split will not solve it: it will multiply it.

1

Chapter 1 — The microservices misunderstanding Microservices & APIs

1.2 What the field evidence says — ten years after the wave

The corpus is now rich: the founding texts (Lewis & Fowler, 2014; Sam Newman, Building Microservices), ten years of public retrospectives — including the openly owned reversals of large platforms that re-merged services cut too fine — and our own engagements. Four robust findings:

The benefit is organisational

The cost is permanent

Where microservices succeed, the observed gain is first human: autonomous teams, deployments made routine, easier recruitment. The purely technical gain (fine-grained scaling) concerns only a minority of systems.

Network between modules, deferred consistency, distributed observability, contract versioning: these costs do not amortise — they last as long as the constellation. They must be paid for by a benefit that lasts too.

Service size is not the subject

Going back is honourable

“Micro” has done a lot of damage: fifty-line services, by the hundreds. The right grain of cut is the business context (chapter 2) — often far bigger than assumed. Better eight right-sized services than eighty fine ones.

Re-merging two overly chatty services is not a failure: it is architecture. Mature organisations refactor their boundaries like their code — in both directions.

1.3 The monolith is not the enemy

The real adversary was never the monolith: it is unmanaged coupling — and it thrives just as well in a constellation as in a monolith. A modular monolith, with internal boundaries aligned on the domains (chapter 2), deployed several times a day, is an excellent architecture — and the best starting point for a possible future extraction: today's well-bounded modules are tomorrow's easy-to-extract services. It is the strategy we recommend by default to organisations that do not yet have the three conditions of §1.4: modularise first, extract later, if and when the need is proven.

1

Chapter 1 — The microservices misunderstanding Microservices & APIs

1.4 The three-conditions test

Three conditions, all verifiable, all necessary. The split only launches when all three are green — and each can be built if it is missing:

1.

Stable, known business boundaries. You can draw the domain map (chapter 2), and it does not change every quarter. A business still in exploration — young product, frequent pivots — gets cut too early: the boundaries will move, and refactoring across a network costs ten times more than across a module.

2.

An operations platform that holds the road. A single pipeline to production, on-demand environments, observability with tracing, progressive deployment (chapter 5). Without this foundation, each added service is one more artisanal operations burden — it is the DevOps prerequisite, in the strict sense.

3.

Teams able to own their services in production. “You build it, you run it” with its conditions (tooled on-call, sufficient rotation): a service without a production owner becomes an orphan — and orphans populate the post-mortems.

The conviction that structures this document

A split is justified by the flow, never by fashion. Every boundary created must hand independent delivery to a named team — otherwise it adds network without removing coupling. Boundaries first (chapter 2), contracts next (chapter 3), technology last (chapters 4-5).

A word on the most frequent case in our engagements: the legitimately ageing monolith everyone wants to leave at once. The answer is the same as in the DevOps white paper: the strangler fig — you extract a first context, in production, measured (chapter 7), and each subsequent extraction is decided on the numbers of the previous one. The big-bang rewrite, for its part, has a failure rate that is no longer up for debate.

1

Chapter 1 — The microservices misunderstanding Microservices & APIs

The decision on one map

Split, modularise or wait — the decision tree

“Who must be able to deliver without asking permission — and what stops them?”

The obstacle is the process

The obstacle is the code, the 3 conditions are missing

The obstacle is the code, the 3 conditions are green

Approvals, environments, pipeline: a DevOps problem. Fix the flow first — the split would multiply the problem.

Modular monolith: internal boundaries by domain, fast deployment — revisit extraction in a year.

Extraction by strangling: one context at a time, in production, measured (chapter 7).

1

3

8 > 80

Goal: independent delivery — microservices are only one means to it

Conditions before cutting: stable boundaries, solid platform, owning teams

Eight right-sized services beat eighty fine-grained ones

What this changes for you

CEO

CIO

ARC

Chief executive. Refuse any “microservices migration” budget that cannot answer §1.1's question: who will be able to deliver without permission, and what stops them today? It is the hundred-thousand-euros-a-minute test.

CIO. Have the decision tree above adopted as the official framework: it takes the heat out of the debate, it gives the modular monolith an honourable path — and it protects you from conference-driven splits.

Architect. Your deliverable for this chapter: the list of what prevents independent delivery, classified code / process / organisation. It decides everything else — and it is worth more than any target diagram.

1

Chapter 1 — The microservices misunderstanding Microservices & APIs

Two trajectories, from the field

Case A — the premature split

A B2C scale-up, 40 developers, a product still pivoting: 60 services in two years, cut by “feature” sprint after sprint. Result: every business change crosses five services, deployments are coordinated by spreadsheet, and only two people understand the topology. The way back: re-merging into 9 business contexts, a year of work — the cost of a premature split is the cost of a round trip.

Case B — the disciplined extraction

A B2B e-commerce player, a twelve-year-old monolith, 80 developers: domain map first, internal modularisation for six months, then extraction of the “pricing” context — the one blocking the most deliveries. One service in production by D90, the pricing team's lead time divided by three, and one golden rule: no next extraction until the previous one has proven its gain in numbers. Four years on: eleven services, not one more — and a residual monolith at peace.

The difference between the two cases comes down neither to size nor to sector: it comes down to the order of decisions — and the courage to say no. That is exactly what the following chapters equip: the boundaries (chapter 2), the contracts (chapter 3), then only the technology.

The deployment-spreadsheet test

A free diagnosis: if your deployments are coordinated in a spreadsheet or a chat thread — whatever the number of services — you do not have independent delivery. You have a monolith, distributed or not. The number of rows in that spreadsheet is your first indicator: it must trend towards zero.

1

Chapter 1 — The microservices misunderstanding Microservices & APIs

Vocabulary — the document's five words

Term

What it means here

Independent delivery

A team's ability to put its part into production without coordinating with the others — the goal of the whole document

Constellation

The set of services and their links — the word is a reminder that you do not operate isolated stars, but their relationships

Modular monolith

A single deployable with strict internal boundaries aligned on the domains — the honourable alternative, and the best starting point

Bounded context

The business boundary inside which a vocabulary keeps a single meaning — the right grain of cut (chapter 2)

Distributed monolith

Services that deploy together and fall together — all the costs, none of the benefits (chapter 6)

The link with the collection

This document assumes the foundations of “DevOps at Scale”: the platform, the golden path, the DORA metrics. If your delivery chain is not in place, read it first — microservices without a platform is a constellation without a telescope.

Chapter 2

The foundations: domains and boundaries

2

You do not cut a system: you cut a business. This chapter gives the method — bounded contexts without the jargon, and the one-day workshop that produces the domain map.

2.1 Cut along the business, never the technology

The natural reflex of technical teams is to cut by layers or by technical functions: the “PDF service”, the “notifications service”, the “customer-data service”. Each seems reasonable; the whole is a trap, because every business change then crosses several services — a new commercial offer touches the catalogue service, the pricing service, the PDF service and the notifications service, which must coordinate and deploy together. You have recreated the coupling, with network on top.

The right unit of cut is the reverse: a complete business perimeter, vertically — its screens, its logic, its data — such that a typical change in that business stays inside. This is the intuition of Domain-Driven Design (Eric Evans, 2003), of which a single concept suffices for this document: the bounded context.

The practical test, jargon-free: take your last twenty business changes and count how many services (or modules) each one crossed. The median must be 1. At 2-3, your boundaries are debatable; beyond, they are wrong — however carefully implemented.

2

Chapter 2 — Domains and boundaries Microservices & APIs

2.2 The bounded context, without the jargon

The idea rests on one observation: in every company, the same words change meaning from team to team. A “customer” is not the same thing for sales (a prospect with a pipeline), for billing (an account with a company number and payment terms) and for support (a contract with open entitlements). Forcing these three “customers” into a single model produces the obese object everyone knows — fifty fields, of which each team uses only ten, and which nobody dares modify.

The bounded context takes the observation seriously: the boundary runs where the vocabulary changes meaning. Inside a context, each term has a single definition and a model cut to its use; between contexts, you translate — explicitly, by contract (chapter 3). The sales “customer” and the billing one become two distinct models, linked by a shared identifier and events.

Why it is the right service boundary: because it is stable (the meaning of a trade's words changes slowly), human (it maps to identifiable teams and experts — Conway's law works for you), and verifiable (the twenty-changes test of §2.1). No technical boundary has all three properties.

The signs of a boundary — to look for in your meetings

— The glossary diverges: two teams use the same word while misunderstanding each other, or two words for the same thing.

— The experts change: the person who speaks with authority is no longer the same — you have changed domain.

— The rhythms diverge: one part of the system changes every week, the other twice a year — marrying them in one deployable imposes the slower one's rhythm.

— The requirements diverge: availability, compliance, volume — different constraints justify boundaries.

2

Chapter 2 — Domains and boundaries Microservices & APIs

2.3 The domain map: the one-day workshop

The domain map is the chapter's central deliverable — one page naming the contexts, their boundaries and their relationships. It is produced in a one-day workshop, with the right people: the business experts of each perimeter (not just their managers), the tech leads, a facilitator who knows how to stay silent. The most effective facilitation technique we know is event storming (Alberto Brandolini): the business is told as a sequence of events — “order placed”, “payment received”, “parcel shipped” — on a wall, and the boundaries appear by themselves where the events change vocabulary and actors.

Three rules make the quality of the result:

1.

The wall tells the business, not the system. Naming existing tables, screens or services is forbidden for the first half: the existing system would contaminate the map — and it is precisely what you want to be able to judge.

2.

Disagreements are data. When two experts fight over a word's meaning, do not settle it: write it down — you have probably just found a boundary.

3.

Each context receives three attributes: an owner (a team, not a committee), a strategic status (differentiating core / supporting / generic — you do not invest the same in all three), and an observed rate of change. These attributes decide the order of extractions (chapter 7).

The exercise's trap: aiming for the perfect map. A map 80 % right, produced in a day and corrected while walking, beats six months of modelling — boundaries are validated by delivering, not by deliberating.