// 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.
35 rules of 70 · Clear filters
Ownership
- 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
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
Data
- 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
Resilience
- 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
Security
- 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
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
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