API Evangelist Conversation with Emmanuel Paraskakis on API Product Management, Spec-Driven Development, and Building in the AI Era

An API product is a product just like any other product, and the product is there to serve your market and your customer. You have to know who your market and your customer is, and if your market is big enough and your customer has that problem and has money to spend, you’ll find success with any kind of product. An API product is no different from any other product. That means you absolutely have to build that API outside in. If it’s serving a public market or a partner market, you have to take into account the usability of it — make it easier to adopt, make it easier to use, just like any other product. If there’s one thing to remember, it’s treat it like any other product. Just because it’s an API doesn’t make it some green-headed monster. It’s just a product, so make it usable and friendly the way you would any product.

The most important thing is the design-first approach itself — it’s very much a products outside-in approach. If the API is a product, you have to get the requirements from the market, put together a design that is only a hypothesis for what a good product should look like, take that back out to the market to validate it, and iterate. That was very important back when it was expensive to build. It’s not as expensive today, but there’s still friction — if you build the wrong thing you’re wasting your good reputation, not just tokens. API design-first in 2015 was a good idea ahead of its time, because the tools were difficult to adopt and it required a mentality change, and people don’t want to change. What’s happening today is we finally have tools that have improved enough to truly do design-first. Everything we were talking about years ago is becoming more of a reality.

All that shift left means is we’re going to make the design and architectural decisions earlier than we used to. We’re not going to wait until we see what comes out of the building process to fix the architecture or the security issues — we’re going to build them in early. The shift-left mentality existed five, ten years ago, even before that, if you were disciplined enough to use automation. You could say, here are the patterns I want to use, apply them at design time and tell me if my design meets them — and if it doesn’t, throw an error and tell the user to do better. The design isn’t a design unless it also meets the technical requirements. The spec isn’t just a human artifact; it’s also a technical design, and that has to be part of it. It’s becoming very easy to do that now with context engineering. The context is what carries the technical specs and the rules.

What you’re talking about is, as usual, human and organizational problems. You’ve got teams aligned on different goals — engineering gets told to ship faster and clear tickets, product gets told it’s customer satisfaction this quarter, revenue the next — and you end up with teams driving in different directions. That happens in pretty much every endeavor, not just APIs. So the biggest and most important thing you can do is bring all the different constituents and teams together. Training is one way; there are others. But you absolutely have to have common goals and KPIs — this is what the team is driving for — and make them consistent. Don’t change it every quarter. With the tools we have now, you can also rapidly integrate the knowledge coming from your team, and that knowledge persists, so over time you build up the entire team’s knowledge and nobody gets left behind.

That’s always been the case — there’s always going to be the next hottest technology, and the conventional logic is you’ve got to jump on it so you don’t get told you’re falling behind. The first thing you have to be comfortable with is that there will always be more new technologies than you can ever learn and capitalize on, so you’ve got to be able to pick. And what conflicts a hundred and eighty degrees with that is the teams who say they’ve been told to be AI-native and move faster, and then you look inside the organization and they’re not even doing the basics. Doing the basics right is the thing that ultimately enables you to move faster and adopt new technologies faster. Customers don’t want the newest technology, they want outcomes. It’s counterintuitive, but you have to align on goals, have systems, have discipline, know where your source of truth is — and that’s what frees you up to do the fancier things you really want to do.

Let me tell you how I do API design these days. I start with two or three documents. The first is the actual requirements document — what I’ve learned from the market about the thing I want to build, and my hypothesis for what would work. The second is a document about the entire market or domain, the objects and the way it works, coming out of domain-driven design. Then I have a series of standards documents — the same API standards we used to keep in Word documents, now in markdown — covering naming, formats, and security requirements. You take those and build user stories with an LLM, and you as a human with taste and experience correct them, because it always misses something. Then you pass in another context document about good OpenAPI best practices, and it builds out the best OpenAPI document you’ve ever seen. Run it through Spectral or Vacuum, because LLMs hallucinate, and now you have a high-quality spec that’s validated against the market and correct against your security standards. Your job becomes building and managing the context.

The biggest problem has always been that we don’t know what the thing is supposed to do — we can’t agree that this is the one spec everybody is discussing and agreeing on. It kind of doesn’t matter what that spec is, as long as everybody can find it in the middle of the night without asking anyone, point to the one place, and say this is what we’re building. Does everybody agree? If you don’t, let’s have a discussion. In the past it was tough for non-technical people to edit YAML and JSON. All of that doesn’t matter anymore, because I can sit in Claude Code and tell it what I want and it translates to any format. I don’t even need to look at the markdown if I don’t want to — I just point to where the source of truth lives, we check it into version control, and we all agree on the version. That’s how you get the humans to work together toward one common, aligned goal. That was our problem in the past, and I think now we’re solving it.

First of all, it is flooding the space, because it’s easy and cheap — anybody can go into ChatGPT and say write me a post like that one that got a lot of likes. That makes it harder for people to actually get the word out. The counterpoint is that anything which is not direct AI slop is going to rise out of the slop. It’ll be very apparent that something is real content a real person wrote. AI is a mirror of what you put into it, and absent any instructions or context it just gives you straight middle-of-the-road stuff that looks exactly like everything else. Can you use AI with your content? Sure, you should. For me, for the most part I don’t use it to write — my best content comes from writing it myself — but I’ll use it to fix parts of my writing and to structure my content calendar. It needs to be an opinion, and the opinion comes only from your takes, your experience, the nuance of being a person.

That’s a loaded question, and it changes a lot. I’m a solopreneur, a company of one, so that necessitates using tools to the maximum level I can. What I do is educate and help people build better products — more specifically API and MCP products, around the integration and connectivity domain. These days you have to be known for a thing that you do, like you’re the API Evangelist; people recognize the persona, the Hawaiian shirts, the things you talk about. You have to decide what your segment is — engineers, product managers, startup founders — and consistently put out value and content. The stack itself is very simple: cloud code and a bunch of skills, and then writing on LinkedIn, where I’m big. I use AI a lot to not forget things, to analyze all the feedback and conversations from my courses and identify the gaps and patterns — not to fix them for me, just to surface them so I can go work on them as opportunities.

It’s really easy to build these skills — Skills with a capital S — over time. If you’re in cloud code, you can tell it, hey, we’ve been doing this process, whether it’s writing or some analysis where you’re looking at a bunch of numbers, put that into a skill and then build that skill up over time so it becomes more and more you, even down to the voice you have. That is a useful thing, especially for something like a corporate blog where I want it in a certain tone and a certain way — let’s make sure we have the guidelines there. You can encode your voice, but you have to put quite a bit of work into it; you can’t just automate it. The social side is still really noisy, and doing that part manually is important, because otherwise you miss a lot of conversations and a lot of things you simply can’t automate.

One thing that’s been working well, and it’s counterintuitive, is in-person events. The signal-to-noise ratio is super high in person — people who show up are very motivated. Go to meetups, look up any major city on Luma, find like-minded people and share opinions. People will remember you from your shirt or your bright red shoes, and they’ll remember what you said and it’ll be relevant for them one day. Same with conferences, large or small — go and speak about the things you care about. Personal connections are the strongest ones, much stronger than somebody following you on LinkedIn. And the consulting work bears that out: companies often bring you in not because you’re saying something earth-shattering, but for the therapist or coaching role. You don’t have an axe to grind or a fiefdom to build, so they listen, and you end up telling them the thing they already knew they should be doing. Coming from an impartial outsider, that validation lets them finally do it.