// RULES
Microservice rules
Best practices for microservices, one rule per page: why it matters, how to apply it and an example. They are grouped into checklists you can apply to a service.
70 rules
Ownership
- An owning team is named
One team owns the service end to end, and the design says which.
CriticalChecked automatically
- A runbook exists
The service has written steps for its most likely failures, so the person on call does not start from zero.
HighChecked automatically
- An on-call rotation or escalation contact is named
The design says who is reached, and how, when the service breaks outside office hours.
HighChecked automatically
API
- Create endpoints accept an idempotency key
A client can safely repeat a POST that creates something, because the server recognizes the repeat.
HighChecked by hand
- API paths carry a version
Every REST path includes a version segment, so a breaking change can ship next to the old contract.
MediumChecked automatically
- Every endpoint is described
Each REST endpoint says what it does, so callers and coding agents do not have to guess from the path.
MediumChecked automatically
- The API is covered by contract tests
Tests check that the service still answers the way its consumers expect, and run before every release.
MediumChecked by hand
Events
- Consumed events have a schema
For every event it consumes, the service records the payload it relies on, so a publisher change that breaks it can be seen in advance.
HighChecked automatically
- Event consumers handle duplicates
Every consumed event can arrive more than once; processing it twice must not change the outcome.
HighChecked by hand
- Event schemas evolve compatibly
A change to a published event never breaks a consumer already reading it: fields are added, not renamed or removed.
HighChecked by hand
- Events are published through an outbox
A state change and the event that announces it are saved together, so one never happens without the other.
HighChecked by hand
- Messages that keep failing go to a dead-letter queue
A message the consumer cannot process is set aside after a few attempts, with an alert, so it neither blocks the queue nor disappears.
HighChecked by hand
- Published events have a schema
Every event the service publishes has a declared payload, so consumers code against a contract and not against samples.
HighChecked automatically
- Consumed events name their publisher
Each consumed event says which service publishes it, so the dependency shows up in the catalog and in impact analysis.
MediumChecked automatically
- Events are named as facts, in the past tense
An event name says what happened (OrderPlaced), not what someone should do (CreateOrder).
MediumChecked automatically
- Events carry an id, a time and a version
Every published event has a unique id, the time it happened, its type and its schema version, in the same place on every event.
MediumChecked by hand
- Ordering needs are explicit
The service states which events must be processed in order and how that is guaranteed, and copes with the rest arriving out of order.
MediumChecked by hand
- Published events name their broker and topic
Each published event says where it is published, so a consumer knows where to subscribe.
MediumChecked automatically
- Stale data is expected and handled
Where the service acts on data copied from events, it says how stale that data can be and what happens when it is.
MediumChecked by hand
Data
- No other service reads or writes its database
The service is the only thing that touches its tables. Everyone else goes through its API or its events.
CriticalChecked by hand
- Backups exist and a restore has been tested
The data store is backed up automatically, and the team has restored from a backup recently enough to trust it.
HighChecked by hand
- Each saga has compensating steps
For every step of a saga that can be followed by a failure, there is a defined action that undoes it.
HighChecked automatically
- No transaction spans services
A business operation that changes several services is a sequence of local transactions with compensation, not a two-phase commit.
HighChecked by hand
- Other services' data is reached through their API or events
The service never reads another service's tables, files or cache. It calls the owner or keeps its own copy built from the owner's events.
HighChecked by hand
- Schema changes are backward compatible
A database migration never breaks the version of the service that is running: expand first, migrate, contract later.
HighChecked by hand
- The service owns its data and says what it holds
Each data store belongs to this service alone, and the design says what is kept in it.
HighChecked automatically
- A read model names the service that writes the data
A service that is the read side of a CQRS pair says which service owns the writes, so the source of truth is never in doubt.
MediumChecked automatically
- Derived data can be rebuilt from its source
A materialized view or read model can be dropped and recreated from the data it derives from, and the procedure has been run.
MediumChecked by hand
- Each aggregate states its invariants
Every aggregate lists the rules that must hold whenever it is saved, so the consistency boundary has a reason.
MediumChecked automatically
- Each saga names its trigger and its steps
A saga the service takes part in is written down: what starts it and the steps of the normal path, in order.
MediumChecked automatically
- Materialized views name their source and storage
Every materialized view says what it is built from and where it is kept.
MediumChecked automatically
- Retention and deletion are defined
For each kind of data it owns, the service says how long it is kept and how it is removed.
MediumChecked by hand
- The aggregates the service owns are declared
The service names its aggregates, so it is clear what changes together in one transaction and what does not.
MediumChecked automatically
Resilience
- Hard dependencies have a timeout
Every synchronous call the service cannot work without has a declared timeout.
CriticalChecked automatically
- Hard dependencies have a circuit breaker or a fallback
When a dependency the service needs is failing, calls to it stop quickly or are answered another way.
HighChecked automatically
- Retries only on idempotent calls, with backoff and jitter
Retry a synchronous call only when repeating it is safe, and spread retries out so they don't pile onto a struggling dependency.
HighChecked by hand
Observability
- Alerts are defined
The service has alerts on symptoms its users would notice, each one actionable.
HighChecked automatically
- An availability objective is set
The service has a stated availability target, so "is it reliable enough?" has an answer.
HighChecked automatically
- Consumer lag is monitored
The service measures how far behind its consumers are and alerts before the delay hurts users.
HighChecked by hand
- A p99 latency target is set
The service states how fast its slowest normal requests should be.
MediumChecked automatically
- Distributed tracing is on
Requests carry a trace context through the service, so one request can be followed across services.
MediumChecked automatically
- A dashboard exists
The service has a dashboard showing its traffic, errors and latency at a glance.
LowChecked automatically
Security
- Every caller is authenticated
The design says how the service knows who is calling, for users and for other services.
CriticalChecked automatically
- Secrets live in a secret store
Credentials and keys are read from a secret manager at run time, never from the repository or plain configuration.
CriticalChecked automatically
- Access is authorized per resource
The design says how the service decides what an authenticated caller may do, down to the individual resource.
HighChecked automatically
- Input is validated at the service boundary
Every request and message is checked against a schema before any logic runs, whoever sent it.
HighChecked by hand
- Personal data handling is documented
For the personal data it holds, the service states what it keeps, why, for how long and how it is erased.
HighChecked by hand
- Personal data stays out of logs and traces
Logs, traces, metrics and error reports carry ids, not names, emails, addresses, tokens or card data.
HighChecked by hand
- Service-to-service calls are authenticated
A call from another service proves who is calling, with mTLS or a signed token. Being inside the network is not proof.
HighChecked by hand
- The gateway states how it authenticates callers
Every API gateway in front of the service names its authentication method, so nobody assumes the other side is doing it.
HighChecked automatically
- Callers are rate limited
Each caller has a request quota, enforced at the gateway or in the service, so one client cannot exhaust it for everyone.
MediumChecked by hand
- Dependencies and images are scanned for known vulnerabilities
Every build checks libraries and the base image against vulnerability databases, and someone owns fixing what is found.
MediumChecked by hand
- Scopes or permissions are declared
The service lists the scopes or permissions its API checks, so callers know what to ask for and reviewers know what is protected.
MediumChecked automatically
- Secrets can be rotated without a release
Every secret the service uses can be replaced on a schedule, or within the hour after a leak, without a code change.
MediumChecked by hand
- Sensitive actions leave an audit trail
The service records who did what to what, and when, for actions that matter in a dispute or an investigation.
MediumChecked by hand
- The database account has only the rights it needs
The service connects to its data store with an account limited to its own schema and to the operations it performs.
MediumChecked by hand
Deployment
- At least two replicas run
The service runs as two or more instances, so losing one does not take it down.
HighChecked automatically
- Cutover is a routing change, not a release
Switching traffic between the old system and the new service is a configuration change that takes effect in minutes.
HighChecked by hand
- The way back to the legacy system has been rehearsed
The team has switched traffic back to the old system at least once, on purpose, and knows what happens to the data written meanwhile.
HighChecked by hand
- CPU and memory limits are set
Each instance declares how much CPU and memory it needs and may use.
MediumChecked automatically
- Traffic moves to the new version in steps
A release, or a cutover, reaches a small share of traffic first and grows only while the metrics stay healthy.
MediumChecked by hand
Decisions
- Key decisions are recorded
At least one architecture decision is written down and accepted, with its context and consequences.
LowChecked automatically
Architecture
- A routing layer sits between callers and the service
Requests reach the service through a gateway or proxy that can send each route to the old system or the new one.
HighChecked automatically
- Behaviour is compared with the legacy system before cutover
The new service is run against real traffic alongside the old one, and the differences are examined, before it serves users.
HighChecked by hand
- One capability is extracted at a time
The migration moves a single business capability end to end, and takes real traffic, before the next one starts.
HighChecked by hand
- The data moves with the capability
The extracted service owns the data for its capability in its own store. It does not keep reading or writing the legacy database.
HighChecked by hand
- The legacy model stays behind an anti-corruption layer
Calls to and from the legacy system pass through a translation layer, so its data model and quirks don't leak into the new service.
HighChecked by hand
- The service names its bounded context
The service says which part of the business it belongs to, so its boundary can be judged and its language is unambiguous.
HighChecked automatically
- Calls back to the legacy system are declared
Every call the new service still makes to the legacy system is listed as a dependency, with what it is for and how failure is handled.
MediumChecked by hand
- The replaced legacy code is removed
Once the new service carries all the traffic, the old code path, its data and its routes are deleted.
MediumChecked by hand