title: How to document an API and still respect HATEOAS?
body: <p>I'm designing a REST-like API over Http.</p>
  
  <p>I need the API Clients (apps, not browsers) to <strong>follow the links</strong> (<a href="http://en.wikipedia.org/wiki/HATEOAS" rel="noreferrer">HATEOAS</a>), not to build them.<br/>
  Also, I'll still use readable URLs for some reasons <a href="http://blog.ploeh.dk/2013/05/01/rest-lesson-learned-avoid-hackable-urls/" rel="noreferrer">that can be disagreed</a>.
  However, if pretty ways to document url templates exist (<a href="http://www.apiary.io" rel="noreferrer">like</a> <a href="http://www.mashery.com/product/io-docs" rel="noreferrer">these</a> <a href="https://developers.helloreverb.com/swagger/" rel="noreferrer">ones</a>), I don't think it is the right way as it could clearly tempt and legitimate developers to build urls themselves.</p>
  
  <p>So, How to document an API in a way that respects HATEOAS ?</p>
  
  <p>We often find <strong><a href="https://www.google.fr/search?q=discoverability%20hateoas&amp;rct=j" rel="noreferrer">Discoverability</a></strong> associated to HATEOAS..<br/> To be honest, I don't think this is enough in real life : where business concepts are multiple, subtle to understand and client developers are not your teammates..<br/>
  <strong>Meaningful names are clearly not enough.</strong></p>
  
  <p>Developers need to make their Client apps ..</p>
  
  <ol>
  <li><strong>Navigate</strong> into the API from the entry url to the relevant documents</li>
  <li>Build valid requests (parameters and bodies) and <strong>interpret</strong> responses with no ambiguity on the semantics.</li>
  </ol>
  
  <p>So, How to document this ?</p>
  
  <ul>
  <li>Are there existing tools that generate documentation this way ?</li>
  <li>Would a "Glossary" be enough to fill-in the gap between discoverability and unambiguous interpretation ?</li>
  <li>Maybe the html representation of the API (Accept:text/html) could return human readable documentation...</li>
  <li>.. any other idea or experience on this ?</li>
  </ul>
  
  <p><strong>Related concepts :</strong><br/>
  <a href="https://mathieu.fenniak.net/stop-designing-fragile-web-apis/" rel="noreferrer">Design with Intent</a>, Versioning, <a href="http://www.crummy.com/writing/speaking/2008-QCon/act3.html" rel="noreferrer">Level 3 API</a></p>