I think separating the documentation step (machine-readable or not) from the actual development process is what makes the entire process painful. It means you have to have parallel development or things get out of sync pretty easily.

I've sketched out some work on using OPTIONS and having the code introspect itself to describe how to interact with the API. Basically with good validation, error messages, and solid/consistent naming conventions, you can take it a long way before you have to step out of the development that you're already doing.

I suggest you look at the work on "interface driven development" with swagger: https://groups.google.com/forum/#!msg/swagger-swaggersocket/...

There's plenty that API providers can do to make things saner for all of us, and themselves. Problem is, many (if not most) of them don't seem to care enough. As users of APIs we are their customers, and we outnumber them. Let's find a way to show them the benefits of making our lives easier.

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.

GET http://wombat.com/resources/foo/apidoc ==> A "RESTful" resource ...

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