Reemphasize design guidance on API first and Code second

[hlgr360]

hlgr360 5:28 PM @salvador.juan: Is this a problem of code before api? Is this another instance of a tool/framework making assumptions rather than us Engineers designing the right API and then implementing it?

when picking up the code, and generating the documentation this makes me wonder .. because I would thought that we should do first the right API .. and then do the code. convinience frameworks are more often than not evil in that regard by thinking that we can get easy lunch on the inside, we screw up the one public interface we should really care about the api is long living .. code is forever changing I suggest you look for the reverse path in frameworks you have a swagger ... lets generate code from it that is API first .. the other one is (potentially) repeating the same mistake which doomed SOA ... take a code signature and turn it into a network accessible interface this led to close coupling and the horrors of ESB hell convinience is a nice to have .. but it should not warp what our priority should be .. to have the right API ... code follows swagger provides tooling to create code from swagger just ad-hoc .... have you looked at https://github.com/swagger-api/swagger-codegen

github.com swagger-api/swagger-codegen swagger-codegen contains a template-driven engine to generate client code in different languages by parsing your Swagger Resource Declaration. here is a blog post from Kin Lane: http://apievangelist.com/2015/06/06/comparison-of-automatic-api-code-generation-tools-for-swagger apievangelist.com Comparison of Automatic API Code Generation Tools For Swagger where he compares some tooling

[hlgr360]

Also add perspective of API user 'outside-in' design http://www.kennethlange.com/posts/7_tips_for_designing_a_better_rest_api.html