One of the high level API concepts I have been championing for a couple of years now is helping API providers move from a code-first approach, to an API design first, or as I like to call it, and API define first approach. The practice of crafting an API definition, applying common API design practices, mocking, documentation, and soliciting feedback on your API before you ever begin writing any code, or publishing your API to a gateway. It is a concept that has clear benefits, and has captured the imagination of many API providers, but it is something that is easier said than done when it comes to actually pushing teams to make a complete shift to being API define / design first--leaving me thinking deeply about what is holding teams back.
Most API architectects, designers, and developers agree that if you can successfully define, design, mock, document, and engage with stakeholders before you formalize your APIs, deploying as code, and launching into production, you will be better off. By doing this, you are shortening the feedback loop with other API stakeholders regarding what they API should and shouldn’t do, and increasing efficiency, agility, while saving resources when it comes to delivering API infrastructure. The biggest challenge with this approach is that once you are ready to actually deliver an API, you still end up having to write code, a process which can potentially orphan the agreed upon API contract that was crafted as part of the API define / design first process, and thus the code then becomes the truth. Leaving most developers wondering where the benefits are when it comes to moving to an API define / design first approach.
There are some API gateways that will let you take an OpenAPI, or other API definition and publish your API, and there are server-side code generation solutions for taking API definitions and producing much of the code you need to deploy, but both approaches still require finish work to make it all reality. There are other cloud services that help you with this process as part of a proprietary workflow, but there are no universal, or complete open source solutions that help you go from API definitions to fully functioning API in one or two clicks. Much of the friction holding us back when it comes to automating and streaming API definition from API definitions is the complexity we accept in our database structures, as well as the designs of our APIs, and everything in between. Always requiring the finish work to actually realize the entire surface area of an API, wire it up to backend resources.
I would say that other challenges introduced are more about dogmatic developer beliefs, than it is about any actual realities. Developers like to write code. Many do not fully understand the benefits of going API define / design first, and have perceptions that the process may be about diminishing their importance and role in the workflow, leaving them more interested in being an obstacle to change, rather than embracing an API define / design first approach. Most times you can overcome this with some education and training, and helping developers see the wider development picture, which also includes the business realities of delivering and supporting the API in production. Going beyond what each individual developers will normally see, and involve them in more of the overall API lifecycle, showing them how wide the feedback loop is between developing an API and getting the feedback from consumer, then applying that to the next version. Something that can be dramatically reduced and optimized with an API define / design first approach.
In my conversations with API providers I am going to be asking more questions about how far along in their shift to being API define / design first, and gather more information what the obstacles were that prevented them from getting there. What the friction along thew way looked like. Working to reach out to a diverse range of API providers who I now are at different points in their journeys. Including some who haven’t even began their journey, and are still just in the early phases of learning about and discussing how to go API define / design first. I am guessing that it is like other aspects of the API sector, and folks are just needing more real-world examples of how to do it, with clear guides, tutorials, and other resources that help them figure things out. Along with a regular drumbeat of stories that help them sell the concept to their leadership, and position things in terms of time, resources, and money save by going to an API define / design first—shifting organizational behavior from a code-first way of getting work done, to something more efficient.
