Making team hand-offs work: API boundaries
Why this deserves attention
An API should expose a stable business capability rather than mirror a database or a single user interface. The important work is to turn the assumption into a visible decision.
Overly granular APIs push orchestration to every consumer and make internal changes externally disruptive. On 26 March 2025, this archive entry records the principle as a practical design concern rather than a product announcement.
Design the hand-off
Look at api boundaries through the ownership and information needed when work crosses team boundaries. The objective is not to introduce more process; it is to expose the few decisions that determine reliability, ownership and future change.
Design around consumer outcomes, make versioning deliberate, and keep platform-specific structures behind the contract. Record the decision close to the solution so that delivery, support and future architecture reviews work from the same intent.
What good looks like
Consumers integrate once against an interface that can survive internal platform evolution. The team can describe the expected behaviour, the owner, the evidence of success and the response when reality differs from the design.
A useful next step is to review one live implementation against this principle, identify the largest unowned assumption and turn it into a bounded improvement with a measurable outcome.
Official reference
Salesforce Architecture: Integration Patterns