Hasn't this idea already been explored with registering media types? Isn't this what REST and all of the HTTP specs were meant to address? You use an existing hypermedia type or register a new one, then any client that can read those media types can read your API.<p>I really think one day down the road, someone will come out with a great "new" architecture and it will be what was outlined in REST.<p>As a side note, I went looking through many of these and they pointed to Swagger documents, which contained lots of URLs. This seemed to be a relevant article on the pitfalls of doing this along with some ideas on moving forward:<p><a href="http://amundsen.com/blog/archives/1147" rel="nofollow">http://amundsen.com/blog/archives/1147</a>
Most of those seem hopelessly simple (Just for the image bit, it only has one thumbnailUrl and no thumbnail size information).<p>I understand that this is a basis for further evolution but these APIs are gonna be hitting version 13 before they are usable in the real world and by that point they will probably be skewed towards use cases based on whoever updated them.
In the Future of Programming, Bret Victor talks about how computers should be able to distinguish the API/language of one another using goal directed programming. Is anyone at work on that? It's nice but API documentation isn't usually the problem.