// 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.
28 rules of 70 · Clear filters
API
- 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 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
- 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
Observability
- 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
Security
- 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
- 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
Architecture
- 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