Definition-Driven API Lifecycle Instead Of Code-Driven API Deployment

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—not actually using OpenAPI to its full potential as a driver across all stops along the API lifecycle.

Getting your hands dirty in the defining, designing, and crafting of OpenAPI definitions is where rubber really begins to meet the road in implementing the API specification. Sure, you can still be autogenerating the specifications from your services and tooling, but you should be actively polishing, and rounding off the rough edges in an API design tool, and putting your definitions to work in an API client like Restlet or Postman to truly define what your API does, or what it doesn’t do. Then taking your definitions and generating server side code, importing into your API gateway, building SDKs, and publishing your documentation and tests. If you skip over getting your hands in there, and actually getting intimate with the requests, responses, and schema of an API, you really aren’t definition-driven, and really just code-driven, which is a much more costly, and inflexible way of doing business with APIs.

One of the biggest challenges in achieving a definition-driven approach to APIs I’m seeing is that many groups still think OpenAPI (fka Swagger) is SwaggerUI (aka Documentation). Most don’t even see the definition behind what they are autogenerating, and have never loaded it into an API design editor like Swagger Editor or Apicurio, let alone within a client tool like Postman. This is something that is only exacerbated with the confusion between what is Swagger and OpenAPI, now that the specification is in the OAI. Code-driven APIs are much more costly, and rigid than definition-driven APIs. While you can still use the resulting API definition throughout the API lifecycle, each iteration, and change will be significantly more costly than if you are working directly from a definition, then mocking, and iterating using a client tool like Postman. Something it will take large enterprises a while to fully realize, as they struggle to realize why their API efforts are returning the results they envisioned.