I have found real value in taking an API design-first approach to crafting my APIs over the years, but I always hit a point of diminishing returns with it once the API is actually in production. I have found this to be true with most of the practitioners I have worked with on the design-first front, and I am always looking for ways to still embrace the principles while aligning with the code-first, usage, and adoption realities of putting an API to work. Design-first gets you to a clean starting line. It does not get you through the messy middle of an API that people actually use.
The APIs for APIs.io and API Evangelist have evolved significantly over the last couple of months, driven by my work to expand the discovery (apis.io) and governance (apievangelist.com) data, content, and insights behind them. The APIs still feel stiff to me. They do not have that real, used feel to them yet. What better way to work that out than to actually use them? With classic approaches, that means I have to go develop an application. I have to write code. But with my MCP tightly coupled to my OpenAPI, I am able to use my API in a more conversational way — one that lets me query, interrogate, struggle with, and push the design of my API forward without building an app first.
I am dogfooding my APIs in a new way because of MCP design patterns. Because I am the primary consumer of my own API, I can rapidly iterate on its design based on what I actually need, and on what I think is compelling and useful about the data, content, and insights inside APIs.io and API Evangelist. I keep a free user and a pro user so I can feel the perspective from each of the plans I offer, and then I also keep a full god-level view so I can add whatever is required to make the paths, operations, and tools genuinely usable. I can have a conversation with my API, and add the resources and prompts I want to guide me through how I am really going to need to use it.
To get even more meta, some of the APIs I am using are the ones I use to govern my APIs. I am still formalizing this process. I am spending the summer having a conversation with my APIs. I am arguing with them to get what I want. If it isn’t there, I tell it to build it. Then I use it. If it doesn’t work to the level I want, I interrogate it further, looking for the solution. Then I build that, and I repeat the loop. My data and content is sprawling — and I see that as a good thing. The interface should help me tame the sprawl, make sense of it, harness it, and use it. Not just fret over it.
I like API design becoming conversational. I like having a conversational interface not just for my APIs, but for the operations and governance surrounding them. In this world, Agent Skills become the stories that shape my world — the repeatable, narrated ways I actually put these APIs to work. Design-first told me what I intended to build. Using-first, through MCP and Skills, is finally telling me what I actually built, and what it still needs to become.
