Connected infrastructure

Choose an API boundary

Editorial edition · 16 November 2026

The idea

An API exposes a responsibility that another system can rely on. A useful boundary follows a stable business capability rather than the current arrangement of database tables. Internal storage can then change without requiring every caller to change with it.

Design choice

Describe the caller's intent, the information needed to fulfil it and the observable result. Keep internal workflow steps private unless callers genuinely need to control them. Publish errors that help callers decide what to do next.

Worked example

A catalogue service accepts a request to publish a product. It validates required fields and returns a publication identifier. The caller does not separately update three internal tables or depend on their names.

Before you ship

  • Name the capability in caller language.
  • Document success and failure outcomes.
  • Test a storage change without changing the public contract.

Examples are illustrative. Adapt the checks to your own environment.

Further reading

HTTP Semantics, RFC 9110

Search the library