Enduring principles on building reliable systems, effective teams, and sustainable API ecosystems. Written to be useful regardless of stack or sector.
Well-governed APIs reduce integration friction, improve developer trust, and lower long-term maintenance cost. These principles apply regardless of organisation size or API surface area.
Every API should begin with an OpenAPI specification reviewed by product and security stakeholders before a single line of implementation is written. The contract is the source of truth — not the code.
Major version sunsets should come with a minimum 12-month notice window. Breaking changes should ship with migration toolkits, not just changelogs. Backward compatibility is a trust issue before it is a technical one.
Stateless, cacheable, idempotent REST for core transactional surfaces. GraphQL earns its place at BFF layers where clients need flexible payload shapes without over-fetching — not as a default choice.
Tiered rate limits, when documented and communicated clearly, enforce fair usage, protect downstream systems, and serve as a natural product differentiation layer. They belong in your developer portal documentation, not just your gateway config.
Government-to-Business integrations sit at the intersection of regulatory constraints, non-standard protocols, and zero tolerance for downtime. What makes them different from standard third-party integrations:
G2B APIs change on policy timelines, not product timelines. Versioning strategies must account for mandatory compliance upgrades with no deprecation windows.
SFTP batch files, SOAP envelopes, and legacy EDI formats coexist with modern REST endpoints. Adapter layers are essential — and expensive if designed wrong the first time.
Every transaction must be traceable, timestamped, and cryptographically verifiable. Build audit trails into the data model from day one — retrofitting them is prohibitively costly.
Effective engineering leadership is not about controlling output — it is about creating the conditions in which good engineering is the path of least resistance.
Engineers should own their domains end-to-end — from architecture to deployment. Leadership sets outcome targets and removes blockers. Prescribing methods is a signal that the wrong person is making the decision.
Tech leads decide implementation. Senior engineers decide patterns. VPs decide trade-offs between velocity, risk, and cost. Decisions made at the wrong altitude create bottlenecks — and signal a team that does not trust itself.
Proven stacks compound reliability over time. Innovation happens at the edges — new tools earn their way into production by solving specific, documented problems that stable tools cannot address.
Most organisations follow a predictable infrastructure evolution. Understanding where you are in this arc prevents both premature optimisation and painful under-investment.
The right choice for speed. The danger is treating it as permanent. The cost of tight coupling is invisible until your first scaling event — then it is overwhelming.
Extract services along domain lines, not technical layers. A “payments service” is a domain. A “database service” is an anti-pattern. Team ownership should map cleanly to service boundaries.
Internal platform teams exist to reduce cognitive load on product engineers. Treat internal tooling with the same API governance rigour you apply to external surfaces. The DX of your CI/CD pipeline is as important as the DX of your product API.
Martin Kleppmann
The clearest treatment of distributed systems trade-offs. Required reading before any architecture review.
Sam Newman
Bounded contexts and service decoupling — the principles that prevent premature extraction mistakes.
Camille Fournier
Essential for navigating the IC-to-manager transition and building honest engineering ladders.
Will Larson
Systems thinking for engineering organisations — the clearest framework for team topology and hiring sequencing.
Tools that have proven themselves in production across regulated and high-throughput environments.