Most teams skip the hardest part of API design — figuring out what to build before writing any code. This webinar is about using AI to fix that.
API strategist James Higginbotham walks through the ADDR process (Align, Define, Design, Refine) and shows how LLMs can compress the upfront discovery work that determines whether an API actually solves real problems. Topics include using AI to surface requirements gaps, generate OpenAPI artifacts, enforce style guides, and design APIs built for machine consumption, not just developer convenience.
.png)
Hey, folks. Thanks for joining us. We're gonna wait a minute or so to let folks come on in from the waiting room, but we'll be starting shortly.
Alright, folks. We're gonna get going. Let's do the nuts and bolts, and then we'll do introductions, and then we'll jump into the presentation. We have plenty of time for Q&A.
The first bit of logistics is that this is being recorded, so you may be seeing this in the far, far future. If so, hello from the distant past. Second, we have a question and answer tab in your webinar screen, and we'd love to have you ask some questions and make this a more interactive event. It's a really interesting and timely topic.
So let's jump to introductions. I'm Dan Moore, a principal product engineer at FusionAuth. I'm joined today by James Higginbotham, an API coach with experience in API strategy and execution, software architecture, and assisting teams in delivering AI API platforms and products. As the founder of LaunchAny, a consultancy, James guides enterprises through their AI and digital transformation journey, ensuring alignment between business and technology through product-based thinking to deliver a great customer experience.
He has published several books, including his latest, Principles of Web API Design: Delivering Value with APIs and Microservices, published by Addison-Wesley. He also offers training courses on this topic at launchany.com.
I met James a decade ago — I think I just wandered up to you at lunch and you were super friendly, and we've kept in touch on and off since then. I ran into you at a conference in the summer and I think we talked about this topic, so I'm super happy to have you here. Let's go ahead and let you take it away.
Thanks, I appreciate it. For those of you tuning in live, please definitely drop your questions in — I may end up answering them along the way. I have a few slides for visuals, but this is going to be an open discussion, so Dan and I are just going to chat and you can throw out your questions.
One of the things I wanted to start with is a bit of where I'm coming from and why we're here today. I've been involved in the API space for about as long as we've known each other, Dan, focused on helping organizations with their API programs.
I come from a development background and a software architecture background, but I've also launched startups and worked in product roles. I blend all of those things together to help people understand how to design an API that we can implement successfully, safely, and securely — but also one that's appealing to humans. Now we have this growth of AI, and machines are consuming our APIs too, so we have to think about API design a little differently.
One of the things I've helped people understand is how to design an API effectively. In the book I wrote with Addison-Wesley — and a self-published one before that on Leanpub — the focus has been on helping people align what the end user goals are with how we design our APIs, so the API helps deliver outcomes, not just raw data. Going beyond JSON, going beyond the HTTP semantics we need to use, and really thinking about how we make an API that successfully solves people's problems. If you're building a product, it will be attractive and will solve problems that your customers need — or maybe developers whose customers need things from it.
So I want to talk about what that process looks like for those who may not be familiar with it, and then how we can use AI to assist in API design, accelerate that process, and help drive toward an actual implementation as well.
Hey, James. Real quick, before you do that — that is such a key point, because outcomes versus raw data is like night and day in terms of how a business responds and what the success metrics look like. And one question that popped to mind — feel free to say "bug off" if you're going to cover this later — but it's harder to judge outcomes than it is to say "the raw data is coming from the API, so this is a successful project." How do you think about judging outcomes?
The align phase kind of focuses in on that, so let me jump right into it. Oftentimes, if you're a developer watching this, you're probably told, "Hey, we need an API. The front end team needs an API." Maybe along the way an architect or someone else has decomposed the solution a little bit and says, "We need an API that does X — code this up, we'll give you one or multiple user stories and you go build it." And then we start getting into some of the challenges. We think, well, I need an API for managing projects and tasks, let's just open up our handy-dandy LLM and tell it what we need and have it build it. It builds it and you go, great, done in a few hours — time to move on.
And then we start asking: did you want to attach files to those tasks in the project management system? What are the permissions and authorization rules? Is everybody allowed to see everything? Are projects completely wide open, or do you need to be added as a collaborator? Do we need to order and reorder tasks and assign priorities? What about project archival — does it just hang around, does it have a completion status, does it show up in reports, does it disappear? What reports do we need? All kinds of questions.
So we think we can go to our LLMs and just say "give me an API," but in reality there's a lot more to it. That goes directly to your question about outcomes, Dan — what are people actually trying to do with this project management system? Is this a simple to-do list? Do we need Gantt charts? Do we need dependencies? What do we need? And sometimes we ask those questions too late. We start coding before we fully understand things. We go, "well, we're Agile — we code, then we recode, then we recode again." And maybe that's a great methodology for prototyping. I see that a lot with the vibe coding trend going on now. It's really handy to prototype something — a picture's worth a thousand words, let's get something in front of people and ask, is this what you wanted?
But that's still an expensive process. We have to deal with code generation; we have to see if the LLM generated it right. Is it using the latest version of all the frameworks? Did it break something because it doesn't know about some new version of a framework — some API change that went from v7 to v8? So we really do have to sit down and think about things. And what I've found is that we, as a development community, have forgotten how to find requirements. We opted instead to write code, which is expensive. We love to do it — it's fun, it's creative. I love it. I work in Ruby. I did Java before — I was on Java 1.0 back in '96. I've worked with a lot of different environments, C, C++, and others, and I love to code. But I don't like writing code that gets thrown away when I've written it by hand.
Now, if you're vibe coding, it's a bit different. But I think there's a necessary step regardless, and I'll explain why AI doesn't really solve all of our problems and why you need a process to think about this.
I call it the ADDR process. It stands for four phases: align, define, design, and refine. It's something you can work in an inner loop — like an OODA loop — where you're learning more, incorporating that, and making things better. But it forces you to ask the heavy questions. The first phase, and that's where outcomes come in, is the align phase.
I like to think of it as "outcomes before endpoints." Do we really understand what people need? Do we have a definition of success? People will use OKRs and all kinds of other metrics — they'll use pirate metrics if they're a startup tracking the different aspects of the product throughout its lifecycle. That's all great. But what defines success? In the align phase, we use something called job stories, and job stories help us think about the job to be done.
For example: if you need your lawn mowed, you don't want to do it yourself, so you outsource it. The job to be done is to have a beautiful landscaping job done, and completion means you've entered into a contract and people start showing up every week or every other week to keep the lawn well-manicured — the lawn's mowed, the bushes are trimmed, everything looks great. The outcome is you have a beautiful-looking lawn that doesn't incur the wrath of your homeowners association. That's the outcome.
We look at it the same way when we think about APIs. Not one single endpoint is probably going to solve all of the problems, but all of those different operations across all those different endpoints will combine to produce an outcome. If we know what the outcome is, we can write automated tests. We know when we're done. It helps us track, manage, drive toward a goal, and drive the delivery process, breaking it down into its natural steps.
So it means asking key questions about what we're trying to achieve and getting into the mindset of the customer. Job stories are rooted in Clayton Christensen's jobs-to-be-done theory: if you're going to build a startup, the best way to do it is to find the problem, find the desired outcome, and deliver the job to be done in the middle. That's your solution — you're coming to the rescue if someone has a problem, delivering an outcome they want to see. We can think about our APIs in the same way, and it's really, really valuable.
It looks like you're about to step into the next phase, but before you do, I just want to jump in. I love that lawn metaphor because it's super concrete. Could you give an example from the software world, which is more abstract? Something that is a job to be done that actually becomes an API — not a hello world example?
Absolutely. The one I use in my training is a bookstore example — think of it like an e-commerce site. Why are you going to buy a book? A lot of UX experts or product managers will write personas: "I have a shopper who wants to do these different things." This is similar, but it boils it down further and says, fundamentally, after you do all that work and find your personas and understand the needs, you boil it down to a job story like: "When I need to gain a better understanding about APIs, I want to buy a book about APIs and have it delivered to my home if I want a print copy, or to my inbox if it's an electronic copy, so that I can learn a new skill." Or: "When I'm part of a book club, I want to buy this book so I can read it and then participate in discussion in an informed way."
When we think about job stories, they tend to be divided into different kinds. The unifying job story covers the big picture workflows, and then you can break those down into smaller sub-milestone job stories. Like: "When I'm shopping, I want to be able to search for books by these different criteria so I can find what I'm looking for" — by release date, author, title, keyword, those kinds of things. Those all become very concrete job stories and you can design APIs to them.
If you don't understand that ahead of time and you start rushing in — you open your IDE, you start building a books model, a books resource, a books API — you're not really thinking about what the actual workflow should be. When we do think about it, it makes a huge difference in how we design and deliver the API. Instead of thinking about just getting data out to the browser, it's about how am I enabling people to improve their lives or get things done.
Great, thank you. And I do have an API book recommendation for anyone who happens to be looking for one.
Yeah, definitely. So just to put this in context — this is how I teach people to design APIs. I do a lot of work with enterprises, and enterprises are interesting because they have very complex workflows. They tend to make things more complex over time, not less. Helping people think about what the job to be done applies whether it's an internal-facing API supporting the workforce and operating model, or something like a bookstore, or a combination. Some enterprises have both external-facing and internal APIs, and this works the same.
I'm going to show you what this looks like and how you can produce some of these artifacts with AI so it speeds the process up. One thing I was hearing a lot was: "It takes quite a bit of time to go through and think about these things and put them into a format that drives our API design. I'm under pressure, trying to do more with less — maybe I'm one of a team of five but we really need fifteen. How do I make this happen much faster?" The ADDR process provides that template and framework, and AI helps us get through it pretty quickly.
The define phase takes the outcomes we've identified and helps us break those into steps and turn them into a map of API resources we're going to need. That's where we start thinking about what properties we need, what it's going to look like, what relationships exist between things, and what operations we need. If we better understand the outcomes and the steps in that workflow from the align phase, we can start to model what this looks like — but the model doesn't have HTTP details at this point. It's just a model that represents what needs to be done.
Then we design the API by transforming and applying all those details — the resources, the operations — and we start applying our style guide. If you're doing RESTful APIs, you start figuring out your GETs, POSTs, and PUTs; you figure out all the resources and the JSON, and that leads you to the OpenAPI spec and other steps. If you're GraphQL, you're figuring out your schema, your graphs, queries, and mutations. If you're gRPC, you're figuring out what services you need, what operations are within those services, and how that's going to look.
So the define phase lets you create that model, and you could produce a REST, gRPC, GraphQL, or all three APIs from that same model. You're going from real-world insights and the job stories you've captured in the align phase into the define phase, which acts as a bridge — taking that information and putting it into a format you can make an API out of. The design phase is a rapid-fire step: let's get this looking like our style guide, using the right HTTP methods, response codes, and so on. And then the final step is to start getting feedback.
Sorry, James — we actually had a question, and I think it fits right into the design phase. It's from Christian, who asks: do you have dedicated agents to do different tasks, like making an API profile or similar?
I am looking into building agents for this. Right now, what I'm showing is really about context engineering and prompt engineering more than anything else. And I'll show you why in just a minute — you need interactivity; the agents aren't going to be able to do things fully on their own. So you're going to need to be able to prompt, and what I've done is figured out how to get LLM models to really understand ADDR and show how to execute it. I'm looking to see whether we can codify that into agents as we go.
A lot of this really is about going back and forth. So you have product managers and UX experts in the align phase pulling things together; you have a technical lead, an architect, or a developer familiar with APIs turning this into a model, designing it as a REST, GraphQL, or gRPC API; and then the final and most important step is to get feedback. Early feedback creates confidence and allows us to collaborate.
The refine phase allows us to go beyond just an OpenAPI spec, an IDL, or an SDL. IDL would be for gRPC; SDL covers the schema definitions, operations, mutations, and queries for GraphQL; and OpenAPI defines all the operations for a RESTful API. But those are just static documents. The refine phase says: let's put something together — either a prototype, mock documentation, or something that shows how I, as the designer, think you're going to need to use my API. Here, tell me if I'm getting this right. And this is all before we've written any code, which means we can understand better what we're really trying to achieve, get feedback, and make changes when the cost of change is much lower.
The further we get into development, the higher the cost of change. We have to change real production code, make sure the new code is production-ready, write or update automated tests, and so on — there's a lot of heavier work. Frank Lloyd Wright said the idea of making a change on the drawing board with an eraser is much easier than making a change to the building with a sledgehammer later. That principle is really important with software development today, especially given limited resources and the need to get things out faster.
Designing a contract like this and then collaborating and unifying around that contract allows your front end teams and back end teams to pull everything together. And as you can imagine, this takes a bit of time — maybe on the order of hours — but the align phase is where you spend most of it. You have to ask a bunch of questions: What data do we need to protect? What are the security constraints? What kind of data entitlements do we need? All of those things you start trying to figure out as you're going through align and define. That's what ADDR is really, really about.
That's great. I had a quick question about the alignment phase. You just talked about all the human work that needs to go into making sure we're building the right thing — which, to be honest, is something you could have read in the 2010s or even the 1980s. Does AI change anything around that collaboration? Like, can it give a UX expert a decent first draft, or help a developer who doesn't have a UX expert or needs to schedule time with one? Or does AI not really play a role there?
It does. The align phase in particular is really useful — whether you're building APIs or not — to sit down and understand and express this. The thing I've found is very difficult for people is knowing how to ask the right questions. Let me share a Copilot session that I actually use to show this.
One thing I realized is that LLM models are really good at asking questions and finding gaps, but they're not really good at reading minds. If you just jump in and say "I want a project management API with tasks and all that," it can only go based on what it statistically thinks you might need. That might work for something fairly generic. But if you're inside an enterprise, unless the LLM is trained on a lot of very specific things for your enterprise, most of that knowledge lives in the heads of the teams you work with.
So we have to sit down and start asking some questions. We can walk through and articulate what we know based on how we work as an organization or what we're trying to build — a series of bullet points, a current knowledge state. I come in and say: "I want to be an API architect. I need to do some API design. Let's use ADDR." I'm using Copilot here with GPT-5 Smart, which uses their pro version behind the scenes and does a great job of reasoning through things and doing research.
I say I want to build a bookstore API and here's what I need — I come up with these bullet points. It's only going to sell books, so I scope it down. I call it Jason's Bookstore. I want to create a series of APIs to support online commerce — shopping, checkout, order fulfillment, tracking, inventory management, and catalog management in the future, but for now let's just focus on shopping. We need to support third-party integration. It's going to be used on web, mobile, and with third-party API consumers.
Then I asked it to give me up to five questions to expand and clarify the requirements before we proceed with API design. And it started getting pretty technical pretty quickly — "What kind of OAuth are you going to use? What are the scopes? Do they want REST? Do they want GraphQL? Are they doing EDI?" And I said, "I'm not quite ready for that yet. Let's hold off on all the technical requirements and focus on business requirements first, and we can go back to the technical side if we want to."
Then it asked me five better questions. This is where it becomes valuable: developers often already know, "I've got OAuth in place, I'm using FusionAuth, I've got an IDP in place — I don't need to worry about that stuff." A lot of developers are in an environment where the enterprise has dictated a lot of things already. But what they don't know is: what questions don't I know to ask yet? The LLM can help with that. So you're getting a kind of align-phase prep — what do I know, and what don't I know?
Now, in my prompting session I answered the questions myself, but in the real world what's really going to happen is: these are good questions, who do we need to get around the table to work through them? And you could be live-prompting, providing input, finding the next set of questions, and the next set after that. Developers can get better at asking questions this way.
These things can then feed into other tools — UX can go build wireframes in Figma, but before they build the wireframes, they need to figure this stuff out. What I've seen is that a lot of UX practitioners focused on UI have a very heavy UI discipline; they're good at designing screens and workflows and will jump right in. But we oftentimes miss critical ideas that might change our workflows, change what we really needed to do, or change the cardinality of things — we built a screen that lets you change a single thing when really we need a list of things with master-detail views and select-and-edit patterns.
Going through the requirements and figuring out what you need and what you don't need is really key. I did another round of questions, answered those, and they were some really good ones. I gave it just a few bullet points — probably the level of requirements you'd get from a "go build me an API" conversation with someone — and said, "What else do I need to be thinking about?" You might not be able to answer them all. That's okay. They give you the questions to ask subject matter experts. That might take a few days to a few weeks if you need to get someone external on the phone and run some things by people. Or everyone might be in the room and you can work through it immediately. Either way, you can use these things to drive everything else.
So James, is this ADDR process — and in particular this kind of question-and-answer with an LLM — something you expect developers and tech leads to do? Or is this something a PM is going to do? Or does it really just depend on the organization?
I think it depends on the organization. In organizations that are very product-centric and hire strong product managers who really understand how to manage a product, they're probably going to be doing a lot of this themselves — they'll get it pretty far before handing it off to the teams, maybe with a technical resource collaborating alongside them.
In organizations where your product managers tend to come more from a PMP certification background — meaning they're really project managers getting their foothold in product — this is really good because it helps them figure out questions they may not be asking themselves. They may not be familiar with some of the nuances of software development and need to get these questions answered before developers start asking them.
In an environment where developers are product-aware or have a product mindset, the developer will actually be the one running through these questions. Or maybe the product manager is too busy, or you don't have a UX expert available to help map things out, so the developer uses this to ask the right questions — from the mindset of "what don't I know to ask before I start coding this thing and have to refactor it a bunch of times?" Like: someone told me we need to support coupon codes and I didn't ask about that upfront. Those kinds of things. So this is really, really beneficial from that perspective.
This allows you to get all your requirements. The next step is to build our job stories, and I'm not going to show you everything here — this is kind of a preview of a workshop I'm putting together, and I'm also exploring whether it makes sense to build actual agents that run through this and interact with you, or whether it makes sense to use the LLM in chat mode to get these things done. I find the LLM-in-chat approach is really beneficial right now.
I could definitely see where you could combine this with some MCP servers that allow you to take the OpenAPI spec when you're done and push it out into your API catalog, or take some of these job stories and push them into a wiki or Confluence so they're captured and not stuck in an LLM session. I think there are some opportunities there and maybe some agents that make sense.
But from a simple perspective, the LLM is really good at asking you questions and guiding you through the process. And what I've found is that a few LLMs — like Copilot, like GPT-5 — already understand ADDR. They've read my book and my resources and can actually coach you through it. If you're not familiar with ADDR, you can ask the LLM to coach you and it'll start asking questions. It recognizes the different phases, enumerates the different deliverables and activities, makes sure you have a full understanding of what needs to be done, gets you to the design, and produces assets you can share to get feedback. That's where a lot of the time savings really are.
Jumping forward in time to show you what this looks like — once you have those job stories and you've broken them down into steps and defined an API, you get a tabular view of what you need: what the response codes will be, what success and error responses look like, what data you need, and so on. It helps you map this out and reason about it. And what's really great about these LLMs is that if you give them your style guide — I'd recommend taking your style guide, using the LLM to turn it into a bulleted list of rules, and then feeding that in or building it into a Gemini Gem or whatever you're using so it has that information — it's going to honor your style guide. Because LLMs are really good at pattern matching, you can give them the rules and patterns you want and they'll fill things in accordingly.
We can go through each of the ADDR steps — though due to time I can't go through all of it; it typically takes me a day and a half to two days to teach this fully hands-on. It allows us to get from our requirements into job stories. Those job stories help us define our acceptance tests, drive everything we're doing, and make sure everything aligns with our goals.
Now we have a breakdown of operations we need to deliver. And this is where we can have GitHub Copilot take the OpenAPI spec, maybe generate some boilerplate, and start generating the implementation of these different operations in sequence based on the order we need to deliver them to fulfill the job story. The job stories and the steps required give us a prioritized list of what we need to do to get from problem to solution — something like a project plan — so we're not going all over the place trying to do a single-shot API build, which nearly never works. We hone it down, ask what's going to work for this operation, have the LLM generate that code, build our tests for it, test to make sure everything's working, and work our way through that job story.
One of the things I really love that LLMs can do — beyond OpenAPI spec generation — is produce things like walk-throughs and sequence diagrams and READMEs and things like that. These resources can get massive. I had it build a huge amount of content. For example, things like: I want to create a cart, add an item to a cart, remove it from a cart, apply a promotion code, check out the cart, save the payment method — and it shows what operations you'd be using. And then you can say, "Do a checkpoint: what am I missing?" If you've got this workflow, have we found all the APIs? Have we missed anything? I found several things I had missed personally when going through this. The LLM is generating everything just fine based on what I tell it, but it doesn't know what I didn't tell it. So it starts asking: "Hey, what about this? What about that?" That's really where this AI-assisted API design comes in.
So with all the subject matter experts in the room — within a matter of an hour or two, depending on how long conversations run — I can have all these artifacts built thoughtfully, verify them, produce those artifacts, and share them with the rest of my team. Front end developers can start using their LLM-driven or hand-coded techniques; back end teams are building out their APIs; and everybody's moving a lot faster — but doing it in a way that still keeps end users first.
And if AI is going to be a participant in using this API, it becomes an actor or persona in our job stories. We build job stories for how the AI is going to be using things, or how we think it's going to be interacting with the API, and we build that into our API design so we don't get caught off guard designing something for humans and developers but not for machines. That allows us to bring all of that in, thinking about security along the way — who's allowed to do what, what kind of authorization rules do we need, how do we configure our auth layer to make sure all that's happening. Really, really powerful, and it accelerates things while keeping you on a contract-driven approach. You're not just vibe-coding some API that nobody can use because no one knows what it's supposed to do — your job stories make sure you're hitting those acceptance tests and passing.
Yeah. You don't want to build the wrong thing as fast as possible — you want to build the right thing fast.
Exactly. Honestly, we don't have a problem writing code fast. We had a lot of tools to help us write code fast even before LLMs came along and demonstrated they could help do some of that. What we have a problem with is building the wrong things. We have zombie APIs just laying out there — they're in production, they're using resources, they're exposed, they might be giving us an attack vector, but no one's using them. No one's paying attention to them. The team has long since moved on to something new.
LLMs let us build code faster and keep us from having to write the boilerplate code that we just, somehow in 2025, still don't have a great way to express at a higher level. There are some frameworks that can help with that, but it's still challenging. So LLMs are writing the code that we don't want to write. That's great — but make sure you're writing the right thing and hitting the right target.
And that was kind of the point of the original Agile manifesto. If you spec everything upfront at all levels of detail and then go build it — which is like a one-shot AI prompt everybody keeps trying — you're not able to incorporate learnings along the way. You spend more time trying to get that one spec right, like we did in the nineties, which I was there for. I wrote my fair share of software requirement specifications — over 600 pages or more that defined every aspect of everything — and then we realized we were wrong.
About how somebody was going to use it, because we didn't get feedback. That was the point of the Agile manifesto: deliver value, do it incrementally, learn, improve, and adjust. Our destination may end up being completely different. We think we want to drive to Denver, but in reality we're trying to get to Estes Park, because someone wants something that only Estes Park can provide. Maybe Denver is a stopping point but not the endpoint. We need to adjust the way we're building stuff, adjust our plans.
This approach allows you to understand what you need, get an API contract in place, start building toward it, and then continue to adjust as needed — in a way that, hopefully, you're not introducing breaking changes in your APIs.
That's amazing. Just a reminder, folks — if you have questions, please drop them in the Q&A tab. I have a couple of questions, but I want to make sure you get through everything you've prepared. So go ahead.
Yeah, let's dive in and keep going.
Cool. You said a couple of things that caused me to think about things differently. I love the metaphor that waterfall is equivalent to one-shot AI code generation. But around LLMs in general — I know you focus on the enterprise — have you had anybody worry about sending their data off to ChatGPT or OpenAI or Anthropic or any of those cloud-hosted models?
Yeah, there's definitely a lot of concern about that. One of the things I'm looking at is that everybody's bringing in a different version — some are bringing in their own in-house versions using open-source models, and some are using hosted models. A lot of people are actually using Microsoft Copilot internally, which I've found is really beneficial. Typically, you're not going to be typing anything into your spec generation that might be PII-related because you're dealing with requirements, not raw data. But there might be some things you don't want shared or used for training, so bringing that in-house is key.
That means potentially training that in-house model on ADDR to make sure it's ready to go — training it on your own style guides, your own workflows, all the different assets. And there are a lot of organizations being very cautious about adopting hosted solutions rather than bringing them in-house. Bringing it in-house means they have to learn a lot more because they're not benefiting from all the work that hosted solutions have already done, so it takes a bit more time to stand things up. Trade-offs everywhere.
And then you talked a little bit about AI as a participant — not in this brainstorming phase, but as an actual actor in the system. I was wondering if you've thought about the differences between designing APIs for human developers to consume versus an agent or other kind of machine consumption.
When we're thinking about agents, we have to do a few things. One is making sure we're documenting our APIs thoroughly — the agent is only going to understand what to do based on the documentation provided. Those that write OpenAPI specs and put in "get the list of projects, creates a new project" and that's all — not very helpful. We're going to have to expand that. What are there mutually exclusive fields? I see that a lot in enterprise: we have two fields that are mutually exclusive — it's one or the other based on the type — and we have to define all of those things. We have to spend a lot more time making machine-readable formats like OpenAPI specs, SDLs, and IDLs complete and thoroughly documented.
The other thing is using the vocabulary of the human. My running assumption is: yes, developers are using these things today; yes, developers want to build MCP servers and tie things in so they have tools for the LLM; yes, they want to build agents. Everybody's all excited about agents these days — just like they were about chatbots before, and services and SaaS before that. We explore these things and see what works and what doesn't.
The reality is that most of the people using the outputs we're building are going to be business users, not developers. If they were developers, they would just use the tools at hand — Postman, Insomnia, API clients, they'd build collections, write scripts, build a web interface or command-line tools. A developer can solve this problem any number of ways. But if we're going to put it in the hands of what some used to call "citizen developers" or "business application developers" — the same people who write macros in Excel — these are the people who can use what we're building to great effect, so developers don't have to stop and build custom queries or reports for them.
If we focus in on that — our goal is to solve human problems using AI and not just to build AI for the sake of it — then we have to speak the business language. Our APIs have to document themselves and have resources named in business terms. If a third-party external business user is trying to use your APIs or your agent and they're prompting, they're going to use a certain vocabulary that you may or may not use in your implementation details.
By using ADDR, we get to understand what vocabulary they're using, which allows us to design an API tailored to the vocabulary of that industry, that market, that user group, that persona — so things are in their language. When they type a prompt, it makes it easier for an MCP host to find the right tool that's registered as an MCP server. When our machines become clients of our APIs, they're finding the right one first off by discovery — because we have MCP registries now, just like we had API registries, just like we had service registries back in the SOAP days. Everything's a registry. Everything's about discovery, and making sure it's basically marketing your API to the machines. Are you marketing it correctly? Are you using the right vocabulary? Are you using the terms they're using? Will the LLM be able to take the vocabulary someone types and easily find your tool?
If it's the only MCP server registered, absolutely. But if there are ten or twenty MCP servers registered as tools to that LLM — maybe, maybe not. Imagine an enterprise with hundreds of useful APIs. If there's a "get account" call for a checking account, another for an auto loan, and another for a home loan — which one is it going to pick? Am I designing and documenting the API effectively enough so the business language can be mapped into this, so the machine can do the right things and come up with a plan effectively — without the non-technical person having to tell it which API to use? Right now, a lot of demos require the prompter to say "use this tool to do this," which means they have to be sufficiently familiar with the infrastructure. Most business folks aren't going to care what MCP stands for or how it works.
And then things like pagination to limit results so you don't bloat tokens. Yes, some of these systems are increasing their token counts fast, but why bloat that session and risk losing something important contextually, or forcing a session restart to reset context because it got a lot of information all at once from the APIs. Being able to filter, sort, and set priority of what comes back first — those are the things machines are going to want, and we have to design those into our APIs. Building that in and thinking about it during the ADDR design process is going to be really key.
So that right there is worth the price of admission to this webinar. The clear understanding that you have to think about your end user — because they're still human beings who are still going to be involved in prompting and interacting with those agents — drives everything. And you can really sense your experience in this, and the fact that you're passionate about it probably means you have some scars too.
We're running a bit short on time, so I just want to make sure we get to one more question — about training the LLM. Do you update rules when it delivers good output? What do you think about training the LLM?
A lot of what I've done so far has not required any training, which is why I love it so much — the barrier to entry is low. The real day-to-day application of these technologies demands that we have solutions out the door, and we need to have that figured out.
If you're building your own LLM in-house, what I've seen people doing is training their LLMs with API designs that they really like, but with kind of mixed results. I think LLMs really love patterns more than they need that sample data set of APIs that worked well. If you give it the rules, it will abide by those rules. A robust style guide and set of patterns will go a lot further toward producing results you actually want in production.
I spend a lot less time training LLMs than I do just doing proper prompt engineering and context engineering: this is what I need, these are my current requirements, these are my constraints, this is what I want you to do. The public LLMs are really good at this. The private LLMs — I'm still trying to get enough sample data on that, partly because a lot of organizations are very cautious about who they let have access, even for internal full-time employees, because of cost, infrastructure, and governance constraints.
So I would suggest: focus on patterns. Pattern matching wins all the time with this. Keep it simple.
That's great. I think we have time for one more question and then we're going to have to wrap up. Jeff asks: what is a good format for a style guide to feed to an LLM? Is it markdown? What does it look like?
A lot of style guides are written in Markdown and published with GitHub Pages or something similar, or written in a wiki like Confluence. The best cheat, Jeff, is to take your style guide — whether it's in a PDF or a wiki you can export to PDF — open up an LLM session, and tell it: "You are an API designer in charge of API governance, and you want to turn this style guide into a prompt so that future LLM sessions can apply the style guide effectively." When you do that, it will extract all the rules and patterns and put them into bullet points, and that's all you need.
Take those bullet points, put them in an external file and attach it, or have them ready to copy and paste in, or build them into a Gemini Gem that's pre-established: "I want to design an API, you're an API architect," the preamble sets the role and includes those bullet points, and then just update that Gem or template as the style guides evolve. If you just give it the raw style guide contents, the LLM has to figure all of that out within the context of the design session, which is a lot less effective. Boil it down into a set of bullet points with patterns and do's and don'ts.
And use RFC 2119. These LLMs love that — MUST, SHOULD, MAY, MAY NOT, SHOULD NOT, MUST NOT. Use that language and capitalize it, and it will help the LLM match on it and know: I'm allowed to do this, I'm not allowed to do this. It gives the LLM the same kind of boundaries you'd give a human designer with guidelines for consistency.
So you're going to want a style guide prepared for your LLM in the format it wants — and just let the LLM build it for itself and then share that out. That's what I've found is most effective. And back to the previous question about training: you could use that to train your LLM if you want something pre-canned and ready to go, so it understands the style guides you use and can pull that information in contextually.
Amazing. Well, I want to say thank you to our audience and thank you to you, James. This is the first webinar I've ever been in that quoted both Frank Lloyd Wright and RFC 2119, so I can mark that off my bingo card.
Really appreciate all the knowledge you dropped. And a reminder to everyone watching: you'll get this emailed to you, so don't worry too much about notes — you'll be able to go back and revisit any of the points. James, do you have any final thoughts?
Just a recommendation: I'm going to be putting a lot of this knowledge into a report and ultimately a blueprint guide, and probably a workshop. If you go to launchany.com/reports — that's "reports" pluralized — I've got a sign-up so you can get notified when the report's ready. I'll also let people know when the workshop is ready and offer a discount code for that as well, so we can sit down live and go step by step. We'll use a simple example so you don't have to worry about using a public hosted LLM for the session. It's going to be really fun stuff. Look forward to having people jump in, and feel free to reach out if you have any other questions.
Thanks. We'll include a bunch of links to James' information and some other resources in the email that goes out. Thanks again for your time, everyone. Thanks for your questions. Thanks, James, for an excellent presentation — we'll see you next time.
Thanks. Bye.
