You hear a lot about being API design first out of the API echo chamber these days. I’m finding that concept to be challenging for many groups I’m working with due to some of uninformed perceptions around REST, leaving many unable to move towards a design first approach because they are worried if they are doing it correctly. I shifted my own thinking a while back to be more about define-first, requiring that I thoroughly define each API project before I begin moving it along whatever API lifecycle I’ve quantified for a project.
One thing I’m finding pretty common across the enterprise groups who have adopted OpenAPI (fka Swagger) as part of their operations is that many aren’t truly using the API specification format to its full potential as an API definition, let alone applying across multiple stops along the API lifecycle. Over and over I see groups “using Swagger”, but when you dig deeper you see the documentation being autogenerated as part of existing development, out of .JAR files, and (thankfully) evolving continuous deployment workflows. While this is progress, it’s not the definition-driven API lifecycle that organizations should be investing in, is is just code-driven APIs
