API Design Fundamentals for Backend Software Systems
Video tutorial: API Design Fundamentals for Backend Software Systems
A line on a diagram is not a boundary. A boundary exists when the two sides have agreed, in writing, on what crosses it: the operations available, the shape of the data in each direction, which fields are required and which may be absent, the errors that can come back and what each one means, and the promises about time, meaning how long a call may take and what the caller should do when no answer arrives. Anything not written down becomes a shared assumption, and shared assumptions are the coupling you cannot see until it breaks. The contract also fixes what is deliberately hidden: the storage the other side uses, its internal names, its release schedule. If a consumer can only work by knowing those, the contract is incomplete and the boundary is decorative. This discipline is not only for calls across a network. The same applies to a message someone publishes, a file another team reads, or a table you expose to others. Writing the contract first is also the cheapest design review available, because most badly placed boundaries become obvious the moment somebody has to describe exactly what crosses them. You will be able to take any two components in a design and write the contract at their boundary, covering operations, data shape, errors, timing and what stays hidden, and treat gaps in that contract as evidence the boundary is in the wrong place.
Video tutorial: API Design Fundamentals for Backend Software Systems