Writing
Tagged “API Design”
- Stable Verbs, Dynamic Affordances
A tool catalog can describe what cancelOrder means without saying whether it applies to this order now. A resource can report current applicability without redefining the operation on every response. The useful synthesis is a stable typed vocabulary plus contextual affordances, with execution-time revalidation and an experiment honest enough to test whether the extra layer earns its keep. Third of three.
- What Runtime Affordances Cost — and Buy
Runtime controls keep the server authoritative about current transitions and invocation targets, but they move work from build time into execution. The relevant question is not whether HATEOAS won: it is whether applicability and binding change often enough to justify traversal, dynamic failure, and weaker static closure. Second of three on hypermedia and agents.
- The Browser Was Only Half the Client
A browser can operate a site it has never seen because it shares the work with a person. That does not make hypermedia useless to machines, but it does reveal what the constraint can and cannot supply: controls can bind known operations to current resources without teaching a client what those operations mean. First of three on the contracts hidden inside HATEOAS.
- Who Pays for the Pressure
Bad API design is rarely bad taste. It is pressure correctly identified and incorrectly located — real forces from inside the implementation escaping into the contract, where every caller pays for them forever. Read through Google Cloud IoT Core, Datadog monitors, and the designs that got the same problems right.