Oakfield Edge

Architecture

Interfaces that survive change

Designing a contract means deciding what two parts of a system can safely assume about each other.

Start with meaning

Suppose an order API exposes a field called total. A numeric type tells the reader little about whether that number includes delivery, discounts or tax. Two teams can agree on a schema and still disagree on the product.

Write a worked example before finalising the field. Include currency, rounding and the moment at which the amount is calculated. Those details determine whether a downstream invoice can use the value.

Consider mixed versions

Deployments take time. An older client can read a newer response, and a background task can process a message written before an update. A contract needs to make sense during that overlap.

Introduce a field alongside its predecessor. Specify how readers behave when it is absent, and check that existing readers tolerate the addition. A change is only additive if the consumers treat it that way.

Give retirement a condition

Removing the old field completes the migration. Tie that step to evidence: supported client versions, queue retention and observed use of the older contract.

Capture a few representative payloads as fixtures and exercise them at the boundary. The fixtures preserve the reasoning behind the transition long after the original discussion has ended.