REST, RPC, GraphQL, event-driven, hypermedia — how you shape an API and what the trade-offs really are.
Yes — it is where governance starts, because you cannot govern toward a standard you have not written down. But a style guide that is not connected to machine-enforced rules will not change behavior.
Hold every protocol to the same set of obligations — machine-readable contract, named owner, security model, versioning policy, catalog entry — while using each one's native contract format to enforce them.
Generate a mock from your OpenAPI document and hand it to consumers on day one. It turns the contract into something people can react to before the cost of change goes up.
Use the language the business uses, plural nouns for collections, consistent casing everywhere, and no abbreviations that require a decoder ring. Then write the convention down and lint it.
Pick one strategy — cursor-based for large or changing datasets, offset for small stable ones — apply it identically across every collection, and document the contract including what happens when data changes mid-pagi...
Use the right HTTP status code, return a consistent machine-readable error body across every endpoint, include something the consumer can act on, and document every error in your contract.
Only if you have a genuine need for independent scaling and deployment, and the organizational discipline to decouple the teams as well as the code. Otherwise you get a distributed monolith with extra operational cost.
Either is fine as long as the result is accurate, reviewed, and version-controlled. Generated specs drift toward describing whatever the code happens to do, rather than what you promised.
URL versioning is the pragmatic default — visible, cacheable, debuggable, and understood by everyone. Header-based versioning is purer and consistently harder to operate.
Design-first means the machine-readable contract exists and is agreed before the implementation is built. It is worth it — but you will not convince everyone, and the realistic goal is a contract that is authoritative...
Hypermedia means the API returns links telling the client what it can do next, rather than requiring out-of-band knowledge. Adoption among human developers stayed small — but AI agents may finally be the consumer it w...
REST thinks in resources and standard HTTP methods; RPC thinks in named actions with parameters. Neither is obsolete — RPC has come roaring back through gRPC.
Documented event types with schemas, signed payloads, delivery headers with an event ID, sane retries with backoff, a replay or delivery log, and a ping event so consumers can test.
When you have graph-shaped data and consumers who need to assemble many related resources in one request — and who are willing to do the work of writing queries. It is a legitimate tool, not a replacement for REST.
When the consumer needs to know that something happened rather than to ask whether it has. If your consumers are polling you on a timer, you owe them an event.
For internal, high-performance, strongly-typed service-to-service communication where you control both ends. Not for a broad public API, where its browser and tooling story remains its weak point.
All of them, deliberately. Mature organizations run a diverse toolbox with HTTP at the pragmatic center and the others deployed where they genuinely earn their cost.
