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