keep API code and API specs/docs in sync...

[miqui]

hi API friends,

..after doing some talks and chatting with other devs there seems to be (my estimation/sense, no exact numbers) two camps when it comes to API doc maint/generation.

using swagger as an example

1 - (code first) write code, run tools to gen the spec

or

2 - design first (and iterate), create the spec (while getting others to participate not just devs) and then code the API - any subsequent changes to the spec need to be 

     applied to the code..... and so on....

IMHO, whatever works for the team/org, but i prefer option 2

thoughts?

thanks...

rgds,

miqui

[Alexander Pletnev]

Hi Miqui.

Both ways works. And both ways are right in case it works for your
current team and current project.

But for me obviously, first way is easier and faster. And therefore
it's better for projects that need to have ability being changed
faster. This way even juniors may work. Less barriers to entry.

Second way is for projects that need more stability. It requires more
efforts and maybe more experience and knowledge. Higher barriers to entry.

Thanks

[miqui]

cool.. thanks for your feedback...

[James Higginbotham]

Hi Miqui,

This question often reveals something more about the team than just documentation - it reveals how they view their API: as a product that provides business value, or as an enabler to integration. If you see your API as a product, you are best served by taking an outside-in approach to your API designs by first designing, then documenting, then implementing. If you see it as code-first, then you are taking a bottom-up approach and focused on delivering an integration that is tightly coupled to your database and other backend systems.

I encourage teams to consider the technical debt they are likely producing as a result of tightly coupling their front end to the backend without taking an outside in approach. Instead, teams might want to consider seeing the value produced by their APIs outside of a single integration solution. See my slides from a recent presentation for more information on this: https://www.slideshare.net/launchany/applying-domain-driven-design-to-apis-and-microservices

Best,

James