The new stack is fully self-documenting for all the new REST calls (not so much for the legacy JSON calls, but these are going away). And the interactive docs are "forced" to keep up, because the interfaces to the real API calls are generated directly from the documentation definitions.
You can see the docs for the current stack here, for example, on our API node: https://api.hive.blog/
One issue is a lot of the API nodes haven't yet updated to the stack we released a couple of months ago (so they don't have the docs either). I haven't really asked why, but my suspicion is that most apps don't yet use the new APIs yet, so there's been little pressure on the nodes to update, and they're probably just planning to update with the next release.
The next release has a lot of key new API calls, so I'm pretty sure the next release will somewhat force all the nodes to update if they want people to use their node. And that's just for the release in Q3. The next release after that is a revamp of the entire hivemind API to be a REST API. At that point, it'll be basically mandatory.
Ok great, I wasn't even aware of the rest API versions. At present, if I visit developers.hive.io I get a fairly complex and tought to parse list of api calls which aren't always supported by all servers or even active at all. So decyphering what exactly needs to be called in order to access specific information can be quite challenging.
I hope that the rest approach and auto-documentation will overcome this. I think that a high percentage of developers from outside of Hive (considering using Hive) will not even attempt to use the APIs a lot of the time - as the docs currently are - because there's too much friction added by these issues.
I'm glad to see the semantic search and 'related items' support coming soon - these are definitely needed. I was going to code my own solution for related items but I'll wait for the updates to roll out instead. 👍