Skip to content

API or RPC Endpoint

Programmatic interface — instantiates Request–Response Capability Provisioning

Exposes the capability as a stable, typed request/response surface at a fixed address, so any client can call it without knowing what happens behind it.

The API or RPC Endpoint is the machine-facing front door of the archetype: a fixed, named address where a client sends a structured request and gets back a structured response — or a typed error — all governed by a published contract. Its defining move is decoupling: the caller names an operation and its arguments, never an implementation, so whatever expertise, data, or computation sits behind the endpoint can change freely as long as the contract holds. Where a human channel routes a request to a person, this mechanism turns the capability into something a program can invoke in milliseconds, the same way every time, with the shape of every request and every reply pinned down in advance. It is the surface, not the machinery behind it and not the rules layered on top of it.

Example

A payments company runs a currency-conversion service behind a single endpoint, POST /v1/quote (or a Pricing.GetQuote RPC). A checkout service anywhere in the company calls it with {from: "USD", to: "EUR", amount: 4200} and receives {rate, converted, quote_id, expires_at} — or a declared error such as RATE_UNAVAILABLE. The checkout team never learns which rate feed, cache, or hedging model produced the number; they code against the contract. When the pricing team later swaps their upstream rate provider and rewrites the model, not a single caller changes a line, because nothing observable in the /v1 contract moved. The result: dozens of internal services converge on one endpoint instead of each wiring up its own rate feed, and the versioned contract is the only thing they all depend on.

How it works

  • Publish the contract, not the implementation. Operation names, request and response schemas, types, and the full set of typed errors are declared up front and become the only thing clients may rely on.
  • Fix the address. A stable URL or service name that clients resolve to, so their code doesn't move when the backend does.
  • Version the surface. Evolve behind a version tag (/v2, a new method) so a changing contract never silently breaks the callers still on the old one.
  • Make errors first-class. Every failure is a declared, typed response (INVALID_ARGUMENT, RATE_UNAVAILABLE), not an undocumented 500, so clients can branch on it deterministically.

Tuning parameters

  • Granularity (chatty vs. chunky) — many small fine-grained calls or a few coarse ones. Fine-grained is flexible but multiplies round-trips; coarse cuts latency but couples callers to larger payloads.
  • Synchronous vs. asynchronous — return the result inline, or return a handle and complete later. Inline is simplest; async becomes necessary when the work outlasts a request timeout.
  • Versioning policy — how long old versions live and how breaking changes are signalled. Long support windows ease clients but multiply the surfaces you must keep alive.
  • Schema strictness — reject-unknown-fields vs. tolerant parsing. Strict catches caller bugs early; tolerant eases evolution but lets undocumented usage drift in.
  • Idempotency expectation — whether the contract promises that a repeated call is safe. Promising it constrains the implementation but lets clients retry without fear.

When it helps, and when it misleads

Its strength is leverage: one integration serves every client, the backend stays free to change, calls are machine-fast and uniform, and the "go find someone who knows how" problem collapses into a documented call. It is what lets a scarce capability be reused without each consumer coupling to its internals.

Its subtler failure mode is that the decoupling is never as clean as the contract claims. With enough callers, every observable behavior — undocumented field ordering, incidental latency, the exact wording of an error — becomes something someone depends on, so the implementation you thought was hidden is quietly load-bearing.[1] The classic misuse is letting the implementation leak through the surface (returning internal database IDs or raw stack traces) so the abstraction is a fiction, or "versioning by never" — changing behavior in place and breaking callers silently. The discipline that keeps it honest is to treat the contract as the product: design it deliberately, version breaking changes explicitly, and test callers against the published surface rather than the current code.

How it implements the components

The endpoint realizes the interface side of the archetype — the stable surface, not the policies that govern traffic through it:

  • addressable_service_endpoint — the fixed, resolvable address clients send requests to.
  • interface_contract — the published set of operations and their types; the stable surface itself.
  • request_contract — the required shape, arguments, and constraints of a well-formed request.
  • response_and_error_contract — the declared shape of a successful response and the enumerated typed errors.

It does not decide whose request runs first (that is Weighted Fair Queue), verify who is calling (Authentication Broker), or guarantee that a repeat is safe (Idempotent API); the endpoint only defines and exposes the surface those mechanisms operate through.

Notes

The endpoint defines the surface but enforces none of the capacity, access, or failure rules by itself. An API published without them is exactly the "infinite black box" the archetype warns against — a stable-looking address whose real limits are discovered only under overload. The endpoint's value depends on siblings supplying admission, scheduling, and failure semantics behind it.

References

[1] Hyrum's Law — "with a sufficient number of users of an API, it does not matter what you promise in the contract: all observable behaviours of your system will be depended on by somebody." It is why a stable published contract still doesn't fully free the implementation to change, and why explicit versioning matters. ↩