HATEOAS: An Alternative Explaination
HTTP APIs have been a huge hit, but HATEOAS hasn&#x27;t. Nobody does it right, nobody &quot;gets it,&quot; everybody must have just misunderstood Roy Fielding&#x27;s dissertation. If only we had a clearer, better explanation, like this one!<p>Unfortunately, this article demonstrates what the industry has known&#x2F;shown for years: that HATEOAS is unsuitable as a technique for HTTP APIs.<p>Imagine writing a programmatic client against the bank account &quot;API&quot; documented in this article, where the way you&#x27;d find out that you can&#x27;t make a withdrawal is not by checking a &quot;status&quot; in JSON and finding it&#x27;s overdrawn, but by parsing the HTML and noticing that there&#x27;s no action link (no `&lt;form&gt;` element!!) that happens to make a withdrawal.<p>Instead of a JSON parser, you&#x27;d now need an HTML parser (one of the most notoriously quirky formats in modern use), but not just that, you&#x27;d also need your client to read and <i>understand</i> that HTML.<p>For example, where&#x27;s the error message explaining <i>why</i> you can&#x27;t withdraw? Why, it&#x27;s written in the page as user-visible text. Which text is user-visible? Uh oh, now you need to parse and execute the CSS on the page to figure that out, too.<p>You&#x27;d need a full-blown browser to do that--a &quot;user agent&quot; as the HTML specification likes to call it--and now, instead of using an API, you&#x27;re screen-scraping the web site by automating a browser with Selenium or Puppeteer or what have you. What will the client do when the server decides to restructure the HTML? Which one of those &lt;a&gt; links or &lt;form&gt; elements represents withdrawing cash??<p>It is <i>possible</i> to develop useful tools that automate full-blown websites, but it it&#x27;s much <i>much</i> easier to develop useful clients when the responses are highly limited in the structure they&#x27;re allowed to return, to couple the client to the server by committing, in advance, to how the API will work.<p>That&#x27;s been Fielding&#x27;s mistake from the very beginning: to think that hypertext provides useful techniques for developing <i>programmatic</i> interfaces. Hypertext is only useful because of its <i>users</i>. Users can read text, understand it, and decide what links to click on or what forms to submit. Programmatic API clients can&#x27;t afford that luxury.<p>As the article demonstrates, if the client was intended to just be a program, we would never use HTML for any of these exchanges, and especially not use &lt;a&gt; links or &lt;form&gt; elements to convey to that program what is or is not possible.<p>The industry has rejected HATEOS not because we were too stupid understand how awesome it is; we&#x27;ve rejected it because we <i>do</i> understand how awesome it <i>isn&#x27;t</i>.