How to document the API and still respect HATEOAS?

Question

I am designing a REST-like API through Http.

I need API clients (applications, not browsers) to follow the links ( HATEOAS ) and not build them.
In addition, I will continue to use readable URLs for some reason, which may not agree . However, if there are nice ways to document url patterns ( like these ones ), I don’t think this is the right way, as it can obviously seduce and end developers to create URLs themselves.

So, how to document the API in a way that conforms to HATEOAS?

We often find Discoverability related to HATEOAS .. Honestly, I don’t think this is enough in real life: where business concepts are few, subtle to understand, and client developers are not your teammates. Significant names are clearly not enough.

Developers must create their client applications.

• Move to API from input URL to related documents
• Create reliable queries (parameters and bodies) and interpret answers without ambiguity in semantics.

So how to document this?

• Are there existing tools that generate documentation this way?
• Will the Glossary be enough to fill the gap between openness and unambiguous interpretation?
• , html- API (Accept: text/html) , ...
• .. ?

, :
, , API 3

Answer 1

, URI , API, URI . API, . , URI , - . :

, - , , , REST URI, , - , ( ).

REST , URI . , "" , - , . , RESTful, , - , , .

- , URI URI , - . , , / , , URI , .

http://osdir.com/ml/web.services.rest/2003-01/msg00074.html

, - URI , , - . , . , URI , URI . , , . , , HATEOAS, . , Street-REST , .

, , API, -. :

API REST (-) , , / . , , , URI, , (, , ). [ , , .]

http://roy.gbiv.com/untangled/2008/rest-apis-must-be-hypertext-driven

, , API URI . , , API Q & A, StackOverflow. , API, , POST rel: answer , , - application/vnd.yourcompany.question+xml - , POST rel: http- .

, , .

, API, , , - REST, , API. , -.

text/html, , rel: doc, HTML - .