Interfaces between systems

Interfaces are designed around what the other side needs to accomplish, not around the shape of the storage behind them. An interface that mirrors the storage underneath turns every future internal change into a breaking one.

Responses are explicit about failure. A meaningful status code and a body that names what went wrong is the difference between a consumer that can handle a problem and one that retries indefinitely against a request that will never succeed.

Anything that mutates state is designed to tolerate being called twice. Networks retry, systems redeliver, and operators re-run things after an incident, so an interface assuming each instruction arrives exactly once will eventually double something that matters.

Rate limits, the behavior of reading large volumes, and the specific ways a vendor's test system differs from its live one are discovered during the build and written down, because the next person to touch the integration will otherwise discover them again at the same cost.

Third-party responses are validated, not trusted. A field documented as always present will one day be absent, and a system that assumes the documentation is a system that fails at that moment with an error naming the wrong cause.

Credentials live in configuration, never in the code itself, and each integration uses the narrowest permission that lets it do its job. A key with full account access used to read one thing is a breach waiting for a reason.

Outbound calls carry timeouts and a bounded retry policy with backoff. A request without a timeout will eventually hang for as long as the operating system permits, holding a connection and a worker, and a system that retries immediately and forever converts a brief outage at a vendor into a sustained one of its own making.

Where an interface must change in a way consumers cannot absorb, the old version continues to work for a stated period instead of being switched off on the day the new one ships.