I believe in going API first. I think it provides a positive step for development teams. I think it is one that makes sense for most enterprise organizations. But if I have learned anything in the last decade of working with APIs is that I rarely get what I want, and people don’t always do what is right and what will make sense. I have gotten a lot of pushback from developers, API providers, and service providers regarding the notion that code first API delivery is bad, as well as the idea that API design first is good. For me, the real challenge here isn’t about selling folks on one approach or the other, it is more about injecting more stakeholders and communication into the process earlier on in the evolution of APIs, rather than waiting until they are baked into production before iterating upon the design of the interface.
There are a lot of existing folks who are trained to deliver code across the enterprise landscape. I’ve heard repeatedly from folks that they are a programmer, and not a templater, artifactor, or API designer. I get it. We have a lot of momentum occurring based upon the way things have been historically, and I don’t doubt that it will be difficult to change our behavior. The challenge here lies around understanding how much of the pushback on API design first is purely about being resistant to change over there being multiple ways to tackle the deliver of an API. I feel pretty confident about there being multiple ways to actually deliver an API, and I don’t care if you are mocking it, delivering via a gateway, with a framework, or hand pounding your artisan APIs on the forge in the workshop. I just care that there is as much light on the overall process, as many stakeholders as possible involved, and there is a feedback loop around what the design of the APIs should be. I don’t care about it purely being about mock, gateway, or code as much as I care about there being thoughtful consideration of the design—first!
I’m not convinced everyone will move from code first. If this is the reality, then we will need continued investment in services and tooling that will render OpenAPI and Postman collections in near real time from common frameworks and gateways, as well as there services and tooling that does the reverse and generate mocks, frameworks, and gateways from OpenAPI and Postman collections. Ultimately it shouldn’t matter, as long as artifacts are available for required documention, establishing a contract for any API being delivered, providing machine and human readable artifacts that can keep all stakeholders informed. Providing the basis for the feedback loop that should exist between technical and business stakeholders who are invested in the successful API outcomes desired.
I have been in the business too long to think I’m going to convince everyone of the merits of API design first. While I strongly believe the benefits of it far exceed those of a purely gateway or code first, I know that other people will undoubtedly see things differently. This is fine, and I will just work harder to emphasize the importance of introducing observability into the process, and the establishment of feedback loop for all stakeholders. I’ll keep working to encourage companies to invest in open source tooling that helps reduce friction no matter which route you choose. While I wish everyone cared about the design of their APIs as much of us analysts, pundits, and architects do, I am not sure we will convince everyone of the merits of API design first, and we will need to accommodate multiple paths to get everyone there, while also keeping our eye out for other newer ways of getting APIs done that might come along in the future.
