We've known for decades that its useful for APIs to be self documented and for responses to use schemas to define the shape of the data.
XML can be verbose and I understand why people preferred JSON for ease use. Had we stuck with REST for the last 20 years we'd be way ahead on that front, though, both in syntax and tooling.
We are where we are because there (sadly) hasn't been a reasonable business case to advance REST API documentation beyond the point of badly-documented OpenAPI schemas where the main utility is in generating type-safe API wrappers across different programming languages.
With MCP, there is at least a name to a new movement to build self-describing APIs, as with the advent of LLMs there is now enough of a utility for it. All other pushes into that direction have died out ~10 years ago.
I do think the problem is from business concerns, though, and are a clear predictor that MCP will fail. Coming out of the dotcom bubble those left standing wanted to build moats and walls, not APIs that any third party could easily discover and use. The need for REST only shows up when a new player makes a move to effectively gobble up the role of being the gate keeper to the internet. With scale other companies will follow, but begrudgingly and only for a short while.
I'm using a REST API to read your comment and submit my response — I didn't need to reference external HN API docs. The interface here is fully self-describing.
In a REST approach, I'd expect an LLM to need some kind of initial entry point, much like needing the initial URL for the HN home page. From there the LLM should be able to parse and discover possible actions, call those actions, and understand the response only by parsing the results and any schemas provided.
In any case, we're on the same page about REST. OpenAPI was mentioned though and I don't think that's ever actually compatible with that type of usage.
I don't think I've ever encountered an API following OpenAPI that was completely self describing and could be discovered and navigated from a single entry URL. They're always paired with some swagger docs or other external content. That instantly makes them not RESTful.
But you're totally right that my comment didn't fit. Might have meant it for the grandparent comment? Not sure.
I make tons of little REST APIs for my agents to use and in the AGENTS.md there's just a list of API entry points with descriptions on what they offer. Agents drive them with `curl` and it all works great.
Anyway - the REST movement served it's purpose - it killed SOAP and forced everyone back to simpler HTTP APIs without tons of over-engineered XML layers so it did well.
SOAP was a pain, XML wasn't doomed though and we didn't need to throw that baby out with the bath water.