This is a very interesting discussion to me. I'm still on the fence about the idea of putting links in API formats. For HTML that works of course, because we understand contexts and meanings. Usually. But libraries have a harder time doing this and semantics only goes so far.
Another short term problem I would see is adoption of this on the API provider side. That's of course something a well coordinated initiative would take care of.
I'm looking forward to seeing where this goes and learning more about it.
We're not so much trying to make this an abstraction layer as we want to make this a library of API definitions that are clear, machine- as well as human-readable (to a point) format, that can be made usable by a connection factory instead of making it necessary to generate and maintain libraries.
This is a good point that we discussed, too. While Hal, like HATEOAS is very interesting and definitely a simplification that's necessary to make our lives better, we're aiming at something different: we're trying to describe existing (ReST) APIs in a way that a single library using a Factory Pattern can turn into connections that you as a developer can use to work with that API.
We settled for the swagger format, because its very flexible, human-readable and honestly can be turned into very nice looking documentation pages.
I'm not knocking what you are doing. I love the effort, and I think it will improve developer experience for the most part. I'm just raising the questions of "Should we have to do this?" and "Didn't we go down this path before?".
The thing that the library is doing, is now replacing a wsdl with an expert that develops a swagger document. This to me sounds problematic. The wsdl had some idea of versioning of the contract, and was dependent on the developer of the service to update the wsdl with updates of their service.
I imagine, and correct me if I'm wrong, but the swagger doc will have to updated by the expert per release of the service (obviously, pending any implementation changes of the service). This actually puts the consumers of the framework at risk of incompatibility via 1., the developer changing the service, and 2., the expert not updating the swagger definition upon 1. Is this accurate?
Please don't take this as me saying that I'd like to go back to wsdls. That is certainly not at all what I'm advocating.
We do intend to version the swagger docs, so that a specific description will point to a matching version of the service. A new version of the doc will have to be created whenever the service is updated. Our goal is to get a large developer community involved, at which point the API owners will find it worthwhile to do this themselves.
Another short term problem I would see is adoption of this on the API provider side. That's of course something a well coordinated initiative would take care of.
I'm looking forward to seeing where this goes and learning more about it.