Learning · Software Engineering Manifesto
Contracts are real APIs
Endpoints and events are commitments — version, compatibility, and ownership beat informal JSON.
Principle
Anything another team depends on is a contract: HTTP APIs, events, schemas, error shapes. Changing them casually is a breaking release even without a marketing version bump.
Therefore we practice
- Own contracts in the producing team; consumers do not silently redefine meaning
- Prefer additive, backward-compatible evolution; explicit deprecation windows
- Validate and test contracts in CI (consumer-driven or schema checks)
- Version or otherwise signal incompatible changes deliberately
- Include correlation identifiers so async and sync hops stay debuggable
Smells
- Optional fields that suddenly become required in production
- Reusing a field for a new meaning because “nobody uses it”
- No schema or sample payloads for published events
- Breaking consumers on a Friday deploy with “small JSON tweak”