[nathanaldensr]

Hold up an object in front of three people. Ask all three to describe the object and what it can do. You'll get three different answers.

The fundamental difficulty with APIs is that they force clients and servers to use the same domain model. Humans are necessary because only humans have the intelligence to reconcile differences in domain models.

The idea of inventing some kind of discovery language is just deferring the difficult work of reconciliation. Computers will need to be as good at induction as the human brain before it will be possible to eliminate humans from the process.

[zdne]

The thing is, why APIs aren't a mix of domain vocabularies? Why the isolated silos with no interlinking?

The Web grew strong because sites were interlinked. REST APIs are supposed to be generalized Web and yet they are missing the links! What Went Wrong?

[nathanaldensr]

The Web grew strong because of the combination of hypermedia and humans. When they look at a hypermedia document like HTML, humans can easily infer context, relevance, value, and a host of other hard-to-mathematically-define things.

I'm not sure REST APIs are supposed to be a generalized Web. In my view, REST APIs are simply a loose protocol on top of HTTP that allow computers running human-written code to communicate with one another. In general, there are several human-driven processes that must occur before REST APIs have any value. Example human involvement: Is this REST API valuable to my business? How much does this REST API cost to use? Does their domain model match ours enough to extract value from integrating with their REST API?

[JCzynski]

HTML pages are a sufficiently limited domain that integrating them is easy. More full-featured domains are progressively harder to integrate, scaling superlinearly with the possibilities added. (Probably exponentially.)