Hacker News new | ask | show | jobs
by cweis 4935 days ago
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.
2 comments
algorithmmonkey 4935 days ago
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.

link
alpinegizmo 4935 days ago
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.
link
eternalban 4935 days ago
GET http://wombat.com/resources/foo/apidoc ==> A "RESTful" resource ...

http://roy.gbiv.com/untangled/2008/rest-apis-must-be-hyperte...

link