A good API is one a developer can use correctly from its documentation alone, and one you can change without breaking the people who depend on it. A gateway in front gives you one place to control and observe all of them.
ContractOpenAPI, written first
VersionsNever break callers
PaymentsIdempotency keys
Every callHas a timeout
Reference architecture
How the pieces fit together
Scroll sideways to see the whole diagram →Callers only ever reach the gateway. Services call each other with timeouts, and share news through events.
Part
What it does
1 Gateway to service
The gateway checks the key or token, applies rate limits and routes to the right service and version.
2 Service to service
Every call has a timeout and a circuit breaker, so a slow dependency fails fast instead of spreading.
3 Events
Services announce what happened ("payment received") instead of calling everyone who might care.
4 Legacy
Older systems are wrapped by small adapters, so they can be replaced later without changing callers.
Design rules we use
Rule
Why
Write the contract first (OpenAPI)
Callers and providers agree before code exists; docs and tests come from it
Never break existing callers
Add fields freely; remove or change them only in a new version, with notice
Consistent errors
Same error format everywhere, with a clear code and message
Idempotency keys for payments and orders
A retried request never charges or ships twice
Pagination and filters
No endpoint returns everything at once
Timeouts, retries with backoff, circuit breakers
Failures stay small and short
Typical tools
Area
Common choices
Gateways
Kong, Apache APISIX, cloud API gateways, Kubernetes Gateway API implementations
Contracts
OpenAPI, AsyncAPI for events
Resilience
Built into frameworks (for example Resilience4j) or a service mesh such as Istio or Linkerd
Untangling integrations, or opening APIs to partners?
Tell us which systems need to talk, who will call your APIs, and what breaks today. We will come back with a plain view of the right structure, what to change first, and what to leave alone.