Why do so few public HTTP APIs reach level 3 of the Richardson Maturity Model, and under what conditions would you argue it is worth the cost?

## The core asymmetry Level 3 fails to spread not because engineers dislike it but because the party that pays is not the party that benefits, and the benefit is contingent on behaviour the payer cannot enforce. The API team pays up front and continuously: a link-rendering layer in every representation, a media-type or convention choice, larger responses, documentation that must explain relations as well as fields, and test fixtures that are meaningfully harder to write and assert on. The benefit - being free to move URLs and to change workflow rules without redeploying clients - only materialises if every significant client actually resolves links at runtime. One consumer that reads `_links.cancel.href` once, notes the pattern, and then builds the URL itself has silently restored the coupling. The server cannot detect this until it moves the URL and the consumer's pager goes off. So the server keeps its URLs stable regardless, and the investment produces no realised return. ## Reinforcing causes **No generic client ecosystem.** The historical argument for hypermedia is the web browser: a single generic client that navigates any site because pages carry their controls. No equivalent exists for APIs. Every consumer writes bespoke code, so the discovery capability has no consumer. **Tooling pulls the other way.** OpenAPI-first workflows, code generators and typed SDKs all describe operations as URL templates plus schemas. They generate exactly the coupling level 3 sets out to remove, and they deliver autocomplete and compile-time checks that developers value immediately and concretely. **Developer experience regression.** A link-heavy JSON body is harder to skim in a terminal or a browser tab. Curl output that is half envelope is a genuine, if unglamorous, adoption tax. **Competing paradigms absorbed the pressure.** Where clients need flexibility, teams reached for GraphQL; where they need speed and contracts, gRPC. Neither is hypermedia, and both solved a felt pain faster. **Weak, delayed feedback.** The cost of *not* doing level 3 shows up years later as a migration project, and by then the framing is "we need to version the API", not "we should have shipped links". ## When the calculus flips Argue for it when several of these hold: - **Un-redeployable clients.** Installed mobile apps or partner integrations with a long tail of versions in the wild. You cannot coordinate a release, so runtime-discovered behaviour is the only lever you have. - **Genuinely state-dependent workflows.** Approvals, claims, order lifecycles, regulated processes - anywhere the set of legal next actions is non-trivial and changes. Here the duplicated state machine is the expensive defect, and links fix it directly. - **A URL layout you know will move.** Multi-tenancy, regional sharding, or an impending service split. - **Long horizon, many consumers, no single owner.** Government and banking APIs are the recurring examples for a reason. ## The recommendation I would actually make Split the two benefits and buy only the one with a payback. Ship **conditional action links** so state-dependent UI decisions come from the server, and keep template-built URLs for ordinary navigation. Publish relation names as part of the contract and test that they appear and disappear correctly with state. That captures the defect-reduction benefit at a fraction of the cost, and it degrades gracefully if a consumer ignores the links. The principal-level signal here is refusing to answer "is level 3 good" and instead naming which benefit you are buying, who has to change behaviour for it to pay, and what you would measure to know it did.