APIs Over IPAs 17: Aligning API Design to Business Outcomes with James Higginbotham, LaunchAny
In this episode, Derric Gilling chats with James Higginbotham, founder of LaunchAny, about designing successful API strategies that drive business value. James dives into his “Align-Define-Design-Refine” (ADDR) methodology, a framework that guides organizations from initial business alignment through iterative API design and deployment. Drawing from over a decade of experience helping companies mature their API programs, he shares practical tips on blending business goals with technical execution, empowering cross-functional teams, and maintaining consistency across the API lifecycle.
They also discuss the evolving role of API product managers, how to embed governance without stifling innovation, and why strong design-first practices are essential for scalable platforms. Whether you’re just starting your API journey or looking to level up your current approach, this episode is packed with actionable advice for building APIs that are not just technically sound but strategically impactful.
Listen to the episode on SoundCloud, Apple Podcasts, YouTube Music, or wherever you listen to podcasts. You can also watch the video on our YouTube Channel.
Table of Contents
- Introduction and Background
- The ADDR Framework
- Adoption and Implementation
- Outcomes and Metrics
- Design and Refinement
- Federated API Coaching
Introduction and Background
Derric: Welcome to Moesif Podcast. Here’s another episode. Joining us today is James Higginbotham, founder of LaunchAny, speaking around API strategy from the initial design process to getting APIs out to production. Happy to have you here, James. Love to hear a little bit about yourself first.
James: Yeah, absolutely. Thanks for having me here. So as you mentioned, I focus a lot on API strategy. The last decade or so, I’ve been working with organizations around the world to help them establish, grow, and mature their API program and to help them understand how to design APIs effectively so that it delivers value to the business. And having a development background, I kind of, you know, walk that line or straddle that line between business and technology. And so I kind of blend those things together where APIs kind of collide with all of that and intersect with all that. So it’s been really fun to do a lot of training, a lot of consulting, and it’s been an absolute blast. So I’m excited to chat with you today.
The ADDR Framework
Derric: Awesome. And just digging into things, you know, I know you like to speak on the align, define, design, refine process, the ADDR process, and this has a lot of obligation, you know, in the API space. Of course, at the end of the day, we want to make sure we’re building, you know, things that are creating value. Tell us more, what does that mean? You know, what is the ADDR process and how does a business get started with it?
James: Yeah. So the origins of it’s kind of interesting about when I started consulting and focusing on APIs about 10 years ago, Keith Casey and I sat down and started writing a book. We were self-publishing it through LeanPub. And then subsequently, I ended up refining this idea of ADDR and publishing it for Addison Wesley back at the end of 2021 And it is really rooted in some of my experience of trying to balance requirements, gathering and understanding what we need with the ability to shift as we learn more to bring that agile software methodology in. So not big A Agile, but little a agile of how do we learn and grow and improve? And since our APIs tend to be forever, once we put them out there and people start using them, it’s very hard to change them. We can add to them, but it’s very hard to change them or remove something that someone’s using. So what I needed was I needed a way that I could repeatedly teach people and people could repeatedly apply in their day to day to go from requirements to an API design. And that’s what ADDR is about.
So it’s broken into four phases, aligning what your business needs are, what your end user needs are, to what your API is going to do. So making sure you understand everything. And that first phase I actually didn’t have in the first iteration of this process. And over time, what I realized was people were coming to me, showing me an API design and saying, what do you think? And I go, great. What’s it supposed to do? What outcomes is it delivering or what problems is it solving? And the developers like scratching their heads and going, well, I don’t know. I was kind of told to build this API and it’s supposed to look a little something like this. And they go, okay, well then we need to have some other parties in here that know what that is.
So what I did is I backed off and said, okay, we need to go back to without swinging the pendulum too far to the old days of waterfall, where we write these 600 page software requirements, specification documents. And believe me, I’ve done that and don’t want to do that ever again, but we also don’t want to just put together an API, not really have an idea of what kind of problem we’re trying to solve, just toss some data over the network and hope that it all works out. And so somewhere in between is what that ADDR process is.
So we align on what we need, and then we define what the API operations need to be in an agnostic way. So I’m not looking at HTTP specifically, just kind of, you know, what are the operations? I need to get something, I need to create something, I might need to calculate something, I might need to orchestrate a workflow, submit, approve, decline, those kinds of things. And so we define what we need to support what we’ve identified in the align phase, then we design it. So we pick REST, GraphQL, GRPC, whatever it is, and apply that technique. And then refine, which is, now let’s get feedback and incorporate that. When the cost of change is lower, when we start getting feedback from our early consumers, and they say, you know, that’s not really what I had in mind, what about this?
And you start working through that, and you say, okay, well, how does that change? Does that change anything from my align phase? Does that change my requirements? Or is this just refining the design and some of the nuances of how the developer’s going to use that API? So that’s the idea behind ADDR. And so I’ve been teaching on it for about a decade, I wrote about it in 2021. And it’s kind of a foundation for everything else that I do.
Adoption and Implementation
Derric: I really like that thinking about the initial business case and requirements before, you know, jumping into design, because, you know, otherwise, sure, it could be a good API design. But as you mentioned, you know, what is it actually trying to achieve? You know, for a new organization that is typically API first, how do they typically layer in this align process? And who takes ownership of that? What does that typically look like for an organization trying to implement this ADDR process?
James: Yeah, when I come in, most of the organizations I work with are enterprise IT. I do work with a few software as a service companies as well, but most of them are enterprise IT. And they may have a few hundred developers. I actually have one client that has 10,000 developers, about 2500 agile scrum teams. And so how that looks in each organization is a little different. Typically, either enterprise architecture or someone responsible for the API program is going to decide we’re going to use ADDR because we like the idea of blending business and technology together and not just running straight in looking at our solution, looking at our data model, and slapping an API on top.
And so it might be a product owner, a director that might be responsible for an API program. If there is an API COE or C4E, like a center of excellence or center for enablement, might be someone from that group. And they’ll use that ADDR process and roll that out. And if I’m engaged, then I’ll do some live training sessions and also license my training content, my pre-recorded training content, so that they can get their staff up and running and familiar with it.
But it really goes back to who’s running your API governance, because this is a fundamental element of your API lifecycle. And so when you look at the governance process, not just how am I naming my JSON fields and, you know, what HTTP methods am I using for what kinds of operations and all those kinds of decisions we might be making, there’s more, from a more broad perspective, there’s the idea of when are we going to use ADDR, who’s going to be responsible for it. And so from a governance perspective, they’re the ones that kind of decide this is what we’re going to do.
And then within each team, typically, a product manager will run with the align phase. They’ll take work that they’ve already done. And they’ll turn it into things like job stories, activity steps, workflow diagrams. And that will then help feed to your architect, dev lead that’s there in that team to help them start transforming that through the rest of ADDR into an API design. So it’s going to be a cooperative effort. It’s very collaborative. And it might be something that one team uses within the organization, or it could be something as broadly deployed as a result of the API governance efforts that they have.
Outcomes and Metrics
Derric: When does one move from one stage to the next? How do I know when I’m done with, say, the align stage and where I have to start defining out these goals and then start designing the APIs themselves? Is there any guidance or recommendations you have for any organizations there?
James: Yeah, there is. I mean, when we’re looking at the align phase, what we want to make sure we understand is that we can identify the problem or situation that we’re trying to solve. And we want to know what the outcome is. If we know those two pieces, then everything in the middle is what we need to work out. And that will tell you when you’re done with the align phase.
And like I said, you know, a lot of product managers, product owners, they have this in their head, they may have it in a Confluence page or some sort of wiki or something somewhere or a diagram or something, but they may not have really transformed it into anything that is necessarily actionable by a dev team to turn into an API. So the align phase, the goal of that is to take the work that’s already been invested and turn that into a format that allows us to drive the API design.
And if that’s net new work, because we’re doing ADDR from the very beginning and we just have a problem statement or, you know, we’re sitting down with business and trying to understand what they need. Great. If it’s something a little bit broad and, you know, and, and all encompassing that we might need to break that down into smaller chunks and focus on one particular aspect of it. It could be that all of the work has been done. A product manager has been working on this for some time, or this is a known issue that people have been working on kind of in the background cycles for a while. And now it’s coming to the forefront. Now this is really important to the business. Now’s the time to go execute and we’ll do that.
And then throughout the rest of the phases, it’s very similar. So in the define phase, you’re going to take those activity steps and you’re going to turn them into an API profile. This sort of just says, here’s what we needed to do. And then you’re going to start making decisions about, well, based on the consumers of who’s going to be using this API, what API design style or styles do I need to use or do I want to use? Is it going to be REST, GraphQL, GRPC, whatever it might be. And we’re going to pick that and start mapping it over. And then we’re going to start socializing it in the refine phase. And we’re going to start incorporating that feedback.
And of course, you can go between the phases. You can hop through. So you might get into, and I’ve done this several times before, you get into the define phase and somebody brings up something and says, well, what about that exception case where this happens? And you go, oh, well, that’s interesting. That didn’t come up during the align phase. So let’s capture that. Let’s investigate that a little bit and see what does that really mean? Did we uncover a new job story, new job to be done? Did we uncover just a new step in the process that we missed or an error case that we missed, but it’s not that big of a deal?
Or is this really opening up things and we go, oh, wow. Okay. Wait a second. What you’re saying is we just did a happy path exercise for a little bit here, maybe an hour or two. And now you’re drawing up and saying, no, no, wait, there are these different phases that this goes through, or there’s these different needs, or there’s different personas. There’s another persona here we haven’t even talked about. And so you can hop back to those other phases. And that’s what they’re meant for, is to put these artifacts into a format that allows you to drive your API design and be effective with it, but also to iterate through it and to be able to jump back when you need to and say, wait, let’s call timeout and let’s go back and revisit something real quick.
So each phase has a certain set of artifacts that it recommends, but each phase along the way also has some exit criteria that says, you know, once we know what the problem and the outcome are, and we’ve figured out what those steps are to get from point A to point B, then we can move forward. And the fascinating thing with that is if we can align on that and build, say, like a job story—when some situation occurs, I want to have some job to be done or, you know, perform some task or something so I can—and I have some sort of outcome.
If I have that framework that I’m working with, I can now define acceptance tests. I can write automated acceptance tests. I know exactly as a product manager when my API has delivered on that outcome. And I know what it’s going to take to get there. And that helps me to understand if there’s a problem to be solved, my API is here to solve that problem. It’s doing the job to be done. And it may be with collaborative interaction with a human or could be in an automated way, you know, all the way through. And then we deliver on an outcome.
It gives us a box or a frame in which we can start thinking about everything else. And it really drives a lot of the rest of the lifecycle and then can drive those discussions and keeps discussions from going off into all kinds of different directions. There’s a time and place for that. But when it’s time to start designing the API, that’s the last thing you want to do is start deviating way far out and start talking about things that are six months down the road. You know, it’s too early to figure that stuff out yet.
Derric: Definitely. And you speak on, you know, outcomes as we’re thinking about, you know, aligning and defining requirements. You know, what are some, you know, good outcomes and, and have you also seen, you know, bad outcomes? And how can a product manager really plan for defining those right outcomes as you’re jumping through these different stages?
James: Yeah, absolutely. And this is actually one of the biggest difficulties that I see, whether they’re a product manager, whether they’re, say, an architect that has a domain expertise and they’re doing the work, whoever it might be, whatever role that might be. It’s pretty challenging sometimes to think about it because sometimes we’re so close to it that we have what’s called the curse of knowledge. You know, we’re so close to it that we can’t really, you know, kind of step back and see things independently. And so we just plow through.
Some of the best outcomes that I’ve seen are things that are transformative to a person. An example might be, recently I was in the health insurance space. We were working with FHIR APIs. We were extending those, but we wanted to go at it from a job story perspective using ADDR, mapping out what the API needed to do, and then figuring out which of those operations were FHIR-related. And we could use the FHIR standards and specification to define how it was going to behave, and then which ones were outside of FHIR. They were, you know, very specific to this healthcare provider. And so in that case, they might be something that they would use FHIR as an inspiration for.
So we started with ADDR. Then we figured out what we needed in the API. Then we figured out how to map it to the standards. And when we did that, one of the things we were doing was a referral. And you think about a physician referral from one physician to another. I go to my general physician, you know, they say, oh, I see something on your skin. I’m going to refer you to a dermatologist. You go, okay, great. And you work with that dermatologist for a while.
Now, what happens if you move, if you relocate? At least within the U.S., whenever you’re relocating, you need to have a referral to get that specialist in that new region you’re in. And that referral process isn’t quite as smooth as it is from like a person within the same network, within the same state, going from a general practitioner, my doctor that I’m doing a yearly physical with, into a specialist like a dermatologist. Not quite as easy to do that when you’re going across state lines, when there’s not some sort of very specific thing happening.
The other thing to keep in mind is with FHIR standards, there’s multiple ways to do things like referrals. They even say it in the guide, in the standards. Hey, there’s about three different ways to do this. So you’re going to have to make sure whenever you build software to check all three of those ways, because the referral could come in three different ways. And you go, okay, so the user experience—or in this case, the patient experience—is not that ideal. So they wanted to optimize those kinds of things.
So what we did is we sat down and wrote job stories. So the job stories were more centered on that patient. You know, when a patient is moving to another state or to another area that’s a specialist or healthcare provider that meets my needs and that has a similar or better practices than the one that currently have. That is a much different problem than just saying, here’s a referral to some random specialist in a place I’ve never gone to before.
To solve that problem, we have to aggregate a lot of stuff in. We can’t just find the list of doctors and pick one. We might want to look at reviews. We might want to pull up other things. So the flow for that is much different than what a FHIR-based standards-based healthcare interoperability standard is ever going to give you. They’re worried about getting data in, getting data out, and data portability. That’s really what they’re worried about. They’re not worried about those kinds of workflows.
Whereas some of the poor job stories I’ve seen is, you know, the opposite of that would be something like, well, when I need a referral, I want to be able to search a list so that I can select the referral that I want. Well, that’s not really producing an outcome. That’s not giving you confidence of where you’re going. So it requires stepping back and thinking a bit more about empathy with the people that are involved and writing that job story in a way that gives them a completion milestone.
Now, it might be a very large workflow, and so this job story is one slice of it, but have we reached some sort of milestone point? Or if we think of it like Mario or something, have we reached a checkpoint? You know, do we reach a checkpoint in our game where we don’t have to go back to the beginning? Have we reached a point in which we’ve solved some of the problem?
And searching doesn’t solve a problem. Selecting something from a search result doesn’t solve the problem. There’s more to it than that. So we have to really step back and think about it differently. And I’ve found that a lot of people when they’re designing APIs, they think about screens in their web app and their mobile app. And they think about clicking through. And they think when they click a button or select something, they’re done. And so that’s a job story. And that’s not.
We might have supporting job stories that break that big idea down into smaller milestones. But the idea is, what’s that unifying job story? And how does that unifying job story change someone’s life, solve their problem, you know, automate something away from them or whatever it is, and look at it that way? That’s how we blend business and tech. Not, you know, using a couple of vocabulary words from the business that they threw out and a bunch of screens. And I fight with that a lot, you know, when we’re starting to work with it, because those skills have kind of atrophied over the years. We used to be really good at it in our industry. And we’re not as good at it anymore. And we have to kind of bring those skills back up. How do we ask the deep questions? How do we understand and gain empathy? And then how do we find out that we’ve actually solved the problem, instead of just pushed someone a step through a process?
Derric: Definitely. And having that customer empathy and thinking about how they’re planning on using, you know, whatever workflow or problem they want to solve with the API—I think that’s always an important piece. We actually sometimes speak on things like managing metrics, you know, looking at a number of requests or requests for a customer. And it sounds like sometimes that could be a really poor metric because, you know, it doesn’t make sense to even have that many requests. And sometimes, you know, APIs can be better designed to reduce number of requests. So to think about things like observability and analytics, you know, how does one, you know, tie that back to the initial outcomes and, you know, have that in place? And what are the right best practices there?
James: Well, I think there are some operational metrics that we have to look at, which is, you know, what you were talking about—requests and error rates and those kinds of things. And those are important for managing our operational side of things. But from a value proposition perspective, you know, they look different to different places.
So for our healthcare, did we find the right person? We verified who they are, and I sent the referral to them. And maybe even there’s a survey at the end and that’s what closes the loop. Did we successfully find them someone that satisfied their need and that they’re happy with? And if not, then did they go, you know, request another referral and try to find someone else? And were they able to successfully do that? And that might be something that runs for a very long period of time. It could take days, weeks, months before that loop closes. And that’s an important metric.
You know, are we giving them enough information? What are we lacking? Did we not have any reviews for the specialist that they selected, and so they just took a chance because it was near their new home that they’re moving to? Those types of things are really insightful and will drive what we do with our platforms, with our APIs, with our internal operations and how we manifest our business capabilities. What are we bringing to the marketplace? What value are we bringing?
If you can help someone through some sort of problem like that, that’s very personal, very serious, very necessary and very scary in some situations—I’m leaving the town that I used to live in to go to another town in another state, and because of job reasons or family reasons or whatever—and now I’m suddenly thrust into trying to change all my health care providers, my specialists as well as my general practitioners. That’s a lot. It’s heavy enough to try to move and relocate and reestablish yourself. And then to not know if you have the health support that you need can be difficult.
So that was one of the things that we looked at there from the metrics perspective—was how satisfied was the person with the referral once they got there, which is a longer term metric.
But to give you a different example, let’s go to banking. Let’s switch from healthcare to banking and think about commercial insurance—sorry, commercial loans. There aren’t that many businesses on a daily basis making an API call saying, I’d like to have a quarter of a million dollar business loan, please. But they happen.
And so the number of requests per second aren’t that important, aren’t very important to us from the perspective of if we’re a commercial business loan organization and we have an API that backs that, and we have these API requests coming in, we might get maybe a dozen requests and we filter those down. Underwriters look at them and then approve three. But those three requests—or those twelve requests—are really important because it gets us down to three approvals from our underwriters, which gives us perhaps a few million dollars across three different people’s lines of credit. That’s going to produce some amount of income over a period of time from interest that we’re loaning.
So the frequency, the quantity isn’t always necessarily the case. We want to know operationally, did that API succeed? And we want to know that we’re resilient enough that when those twelve come in, we can receive all twelve and process them successfully, get them queued up and get them processed. But we might not have billions of requests per day or per month like you might see in some other businesses. But every one of those requests comes with it the potential for tens to hundreds of thousands of dollars of revenue for the business.
So what it does is it means that we have to look at both the operational side when we look at metrics, but we also have to look at the business side. And you can’t look at the business side if all you’re doing when you’re designing your APIs is looking at your data models and saying, yep, I’ve got an application form for a commercial loan in this database and here’s how it’s modeled. So I’m just going to turn that into JSON and that’s what they need to submit. Okay, that might be a good starting point, but what are your metrics? What are you trying to do? What are your goals? Who’s using this? Who’s allowed to call into this?
Do you have—this is where it gets into the business ecosystems or the digital ecosystems you’re in. You may be in a country where there’s, you know, open banking standards and you need to participate in those open banking standards. But what you do is above and beyond what those open banking standards handle. So you have to think about, well, how am I going to balance an ecosystem that demands I have interoperability and data portability and data privacy with these additional differentiating capabilities that my business is delivering? And how do I blend those things together?
Well, if I just look at one API platform that has one ecosystem, it’s never going to click for anybody. But if I think of one API platform that’s catering to different ecosystems, then it’s different. And that—that’s the difference. So our metrics, our observability can be both business side and operational. And I think sometimes we get caught up in the operational. We just want to know is the API working because we deployed it and just make sure there aren’t any issues and, you know, our SLAs are being met and things like that. And that is all good stuff.
But if the API doesn’t deliver on outcomes and we’re not measuring that, then we’re missing out. And so sometimes it means looking at what that lifecycle is from the business perspective and capturing metrics along the way or tracking the lifecycle of that resource—that API resource—as it goes through the different phases of its lifecycle until it’s approved or declined or, you know, whatever that workflow is.
Derric: Yeah, definitely. And I guess separating out the operational metrics and the business metrics, that’s always an important piece. Us as engineers, it’s easy to, you know, get too caught up in, hey, there’s no errors here, or we have some nice performance metrics. But, you know, customer doesn’t care about performance. They care about the outcomes.
As you’re thinking about, you know, these different business metrics, you know, when are they defined? Are they defined at the very beginning, you know, during the align phase? Are they defined later on? And, you know, how do we make sure that, you know, we have the right outcomes and metrics that we’re defining that are truly measuring the value that the customers are expecting out of the platform?
James: Yeah, usually the business metrics I try to encourage in the align phase. If we can’t define the metrics by which we’re defining success or value has been delivered, then we don’t understand the align phase well enough. We need to spend some more time. And that’s really what it comes down to.
Now, it doesn’t mean that that’s your only time to identify them. And what we might do is we might identify three to five, you know, key metrics. And these are the key metrics that tell us we’ve delivered on the workflow—we have success or we failed in this area, you know, we didn’t deliver what we’d hoped to deliver, but the workflow completed. You know, those types of things—wherever the decisions are being made and so on.
And then over time, we might decide that we have more. We might find a few more. Or we might take one metric and say, you know, it’d really be helpful if we could break that down a little bit further. So we take the key metric that says yes or no—decision was made, decision was not made, or decision for or decision against, whatever that metric might be—and then say, okay, let’s break that down and say, how far did we get? What were the metrics along the way? How long did it take us to reach that decision?
You know, how long did it take if we said we need some more documentation to process this insurance claim or, you know, or to approve this business loan or whatever it is? How long does it take for us to communicate back and forth? And can we now optimize that flow and ask for it ahead of time? Because 90% of the time, we’re going to need it anyway, but we just weren’t asking for it.
Those types of insights come as you mature the product. And it just takes a little while to be able to figure that out. But at least starting with a few in the align phase is really important, because it also tells you, you know, where are you striving to deliver? You’re not just pushing data over a wire. You’re changing someone’s life, hopefully in a better way, in some way. Even if it’s just capturing the canonical to-do list or whatever it is, you’re doing something to help someone.
So do we understand enough about the problem? Do we understand enough about the solution? Do we know what those metrics are? And then where are those key metrics going to be gathered based on how the API’s operations are going to be orchestrated through the workflow to some sort of end result?
Design and Refinement
Derric: Makes sense. And just, you know, jumping ahead—now that we’re aligned on what the right outcomes are and set some goals and define those goals—you know, what’s next? How do we actually start thinking about designing the APIs in the right way, given those initial requirements?
James: Yeah. So the define phase, it comes after align. And what that does is helps us take the steps, the tasks, the work that we have to do that we found in the align phase and turn those into some sort of definition of an API. And, you know, a lot of times we focus on CRUD APIs in the REST world. And that’s kind of unfortunate, but I like to use the example of a content management system and the one that you have multiple parties involved.
So you have an editor that has to approve things. Well, you have a workflow now where you create a draft, you work on it, you submit it, the editor reviews it, they approve it or request revision. And so you have this workflow that goes beyond CRUD. And so when you identify those types of things in the define phase, it helps you to understand what are the resources you’re probably going to need and what are the operations you’re going to be performing.
And I like to encourage people to diagram during the define phase. And that’s usually using things like sequence diagrams—or maybe a use case or a sequence in text or something that says, first, I’m going to call this operation and pass in this value, and then I’m going to take the result of that and I’m going to call this next operation, and so on. And it lets me see not just each operation in isolation, but how they collaborate together. And that gives me an API profile in the define phase that helps me understand what my API needs to do. It gives me a surface area to focus on.
And if you’re in a large organization, you may have different services laying around that do some of these things. You don’t necessarily need to build net new everything that you’ve identified, but you’ve identified what you’ve needed. And that gives you kind of a list. It’s like a shopping list—here’s what I need, here’s what I’m going to need. Now, what do I already have? So I’m going to go search my API catalog, my service catalog. What do I have? What can I leverage? What do I need to build net new?
And then I can go into the design phase. And the design phase is where I take that profile that defines how everything’s going to work and helps me understand what my resources are and how everything’s going to behave and how it’s going to flow through the different API operations, how they’re going to be called in sequence and so on, and start turning that into an actual API design. So I’ll take my REST API style guide or my GraphQL style guide I might have or whatever it is that I’m using and start applying those things into the design. So I take that profile and start transforming it into a design, and then I capture an OpenAPI spec and so on and go from there.
Derric: And is there something we can do during the design phase to make sure it’s still meeting the initial outcomes that we’re defining initially? Or what are the kind of the gates that we consider this as design completes?
James: Yeah, so when we go from the define to the design, it’s a pretty straightforward mapping. So we’ll take that profile and we’ll map it into something like a REST API or whatever. The refine phase is really where we spend a lot of our time saying, does this really map back? So we’re always going back to our align phase. Every artifact we produce in the ADDR process is used and reused.
So when we get to the point where we have, let’s say, a high-level API design that maybe we’re not quite ready to put it in an OpenAPI spec, but we know—get to this path, post to this path, and so on—and kind of figure those things out. I can now start diagramming that. I can start writing a README doc to—almost like a getting started guide—and say, here’s how it’s going to work. I could transform that into some Postman collections and maybe have an OpenAPI spec generated for me or something else—whatever. I generate the Postman collections, generate OpenAPI spec, and explore it against a mock API.
So I might have one of those mock API tools that are out there generate a mock for me and I can just bang against it inside of a series of Postman collections or whatever it is—curl or whatever—and start playing around with that API and put it in front of other people. So it’s no different than if somebody were to take a Figma sketch and put it in front of someone and make it interactive, and you try it out and you like it, and they go, okay, now let’s turn it into HTML. You put it in HTML. Okay, how does that work? And we kind of work our way through it and we increase our fidelity as we go and get closer and closer to the real thing as we go.
It’s the same kind of concept. So that refine phase is—yeah, the goal is to get that feedback and to produce just enough artifacts to be able to get that feedback. And I’ll tell you, when you’re designing an API and you have to write a README doc of how you’re going to use it, before you even put it in front of a consumer, you’re probably going to find some things that you missed or some things you want to improve or, oh, that’s just not—you know, it didn’t look right or whatever the case is.
So that’s what that is. And that helps you kind of get to a closer, ready-for-production API design. And this can go—once you get familiar with ADDR, it can go pretty quick. Particularly if it’s a moderate or small scoped item, you can sit down in a couple hours and figure something out. Sometimes I’ll have a couple of days where we’ll sit down in a conference room and workshop with people and get the right subject matter experts in the room.
But after all of that, now you’ve freed up everybody. Front-end developers can start working against the spec. Back-end developers are starting to code against the spec. While some of that’s happening and the contract’s being defined for the API, you might have a couple of developers doing some technical risk mitigation by looking at, hey, can I query this data? Is the data of good enough quality to be able to do what we’re asking you to do? They’re investing in that while you’re designing the API. And then everybody comes back together. You have that one asset and you’re ready to start moving forward.
And you can still continue to refine that as you go based on other learnings and things, but it gives you a really solid contract that everybody can confidently move forward with. And it gives you the business metrics you need. So now you have your product team, your tech team, your ops team can start seeing, well, how many API calls are you going to need to be able to get something done? Well, we’ve mapped that out because we had to do that in the refine phase.
So a lot of those different elements all come together with this. And it makes for a more collaborative and smoother process because we’re not tossing things over a brick wall and hoping the next people understand what’s going to be required because they weren’t in those meetings that you were in, but you didn’t write it down or you didn’t convey it in a great way. So collaboratively working is really important. It helps to refine that design as you go because you’re never going to get it right the first time, but to be able to refine and improve it is really critical.
Derric: That’s a really interesting point of thinking about drafting a README and almost forcing yourself to what it would be like for the customer to use the API and help drive some empathy even before coding it, right? So it sounds like that could be a key piece to the design and refine phase. You know, what happens after refine? So it sounds like it jumps right into development. And when do we go back into the ADDR process?
James: Yeah. So it’ll—at that point, then you have a really good solid, collaboratively designed API design that you’re ready to start doing delivery on. And then ADDR will usually start over again whenever you have a new piece of scope going on.
So now on larger scoped efforts, ADDR—you’ll spend a lot of time in the align phase, and then you might take a slice of that and take it through the rest of ADDR. So you might say, okay, I’ve got a pretty large scope effort here. Let me take this first piece—you know, maybe I found six job stories. Let me go ahead and let’s map out all the job stories and all the activity steps, make sure we get all of our domain vocabulary and all that sussed out and we understand what’s going on as a whole. Now let’s take the first job story and let’s deliver that one. And then we’ll come back.
So in some cases, you’re just going to revisit the artifacts you’ve done, validate, you know, nothing’s changed. Have we learned anything since we released that last—those last set of API operations and maybe tied them into a frontend and received some feedback from someone—end users or other stakeholders? And then we’ll just take what we’ve already done and start executing that, you know, refining it as we go.
In other cases, maybe the ADDR process is really a one cohesive API and we go through the ADDR process and we work through that and we deliver that API. Now we’re kind of more in the delivery management side of things. We’re dealing more with ops. We’re still looking at that. Now your product manager is coming around and saying, okay, let’s take some of what we’re learning now. We tried to roll this out and it was a little too difficult. It was missing this capability. Or, you know, we’ve got this opportunity—now someone approached us and they’re wanting to do business. We’ve got a business development opportunity. Let’s go explore that. And we’d use the align phase at least to do that.
So I’ve seen some organizations—they’ll spend time in align phase and then they’ll stop for a while and they won’t immediately go into the rest of ADDR. They’ll use the align phase to help capture everything that’s important and then they’ll validate. And then if they get, you know, funding or if other business decision makers say this looks like a viable path, we’ll keep going. If not, we’ve done the align phase and then we’ve explored enough to say—or maybe align and define—and we know roughly how big is this bread box of an API that I have to build and how many people am I going to need and what’s the cost going to be to build this thing. And then they might decide, let’s put a pause on it or let’s expedite this. And so it’ll just loop around like that.
And if you could imagine an organization like I’d mentioned before that has 10,000 developers—they have 2,500 teams—they’re all building APIs all the time. So this particular group, this particular company, they have at least 6,000 internal APIs. So they’ve been producing APIs for quite a while. So it’s not like they’re building them every day, but in a given calendar quarter, they’re probably building one or two. And for whatever reason they need, or they’re adding on to an existing one or something.
So you’re doing this ADDR process in tandem with all these different teams. So you can imagine—I mean, it’s just, you know, plates are spinning all over the place. And if you had a centralized group that was required to do the design of every API, their plates would be falling and breaking. They wouldn’t be able to keep them spinning long enough to keep everything going and to be able to talk about all the business metrics and understand each domain nuance and everything else.
And so that’s where I get into federated API coach programs, where you train coaches to support the teams out on the edge doing development for those larger scale situations.
Federated API Coaching
Derric: What is this federated coach process? I’m curious now.
James: So I think what I’ve come to realize is as much as we assume that anybody that can write code can design an API, that isn’t always the case for a variety of reasons. They may not be familiar with API design, or maybe they are, but they don’t know the domain very well. Maybe they’re contractors brought in to supplement a team or something, and they just don’t know the domain very well, or whatever it is.
So what we realize is you cannot build a large enough center of excellence or center for enablement—an API core team, an API guild, an API office—there’s different terms for it in different companies. But you cannot build an API practice with enough people centrally located full-time to be able to support the number of developers that are in your organization, even if you only have a couple hundred.
Because they’re always going to be asking questions. They’re always going to be requiring you to spend a few hours to understand how does their domain area work. You know, I don’t understand e-commerce. Maybe I don’t know anything about API payment gateways and payment processors and all that. Or maybe I don’t understand how to send a text message, and I don’t understand SMS networks and so on and so forth. Or I don’t understand claims and insurance. Or I don’t understand how to underwrite an insurance policy. Or I don’t know how to underwrite a loan for, you know—or whatever it is.
So if you had a centralized group, they’ve got to understand all those domains at any time, all the time. And it’s just nearly impossible.
So a federated coach program recognizes the fact that the COE or C4E is probably made up of one, two, five—a small number of people that are passionate about APIs and bring their technical expertise, their product expertise, their management expertise, their network connections within the organization to other executives and so on that helps to tie all of the initiatives together that are going on, all the big things that are happening.
And then the coaches are people that are passionate about APIs, but they live in different parts of the organization. They’re not in the COE. So they have more like a dashed line or a dotted line to them.
So what the COE does is we—and what we do is we train up these coaches. We make sure that they understand how HTTP works, how to design APIs. We make sure that they can design with ADDR. And then we work on making sure that they can facilitate design sessions. That’s an entirely different skill. It’s an entirely different skill to be given an API design and then try to figure out how do I change it? How do I need to improve it? What patterns have I seen before that might apply here?
That’s much different than sitting down designing an API—one singular API. It’s a scale that’s much different and the skill set is much different.
So what we do is we make sure that everybody has that base foundation. And then we go through training and we talk about how do you facilitate design discussions, how do you facilitate the align phase, the design phase, and so on all the way through ADDR. We talk about how do you do design reviews and do it in a way that’s positive and constructive. How do you make sure you’re clear about your design reviews so that someone doesn’t go off and spend three months redesigning something because you said, “Hey, wouldn’t it be great if…”—and they thought that was a demand of that person to say, no, this API is not going to go out the door until you’ve done this thing. No, that’s not what I meant. It would just be great if—
So the difference between required changes to your design to comply with your style guide or to make it a little bit more flexible or better fit or reusable or whatever it is, and recommendations that if you have time or if your framework, programming language allows you to give you an affordance to do something, you can do it.
So these coaches—they exist out on the edge of the organization. They’re in the domain areas. They’re in the different lines of business or different domain areas. And they’re out there and they’re blending. They’re acting like representatives of the COE or C4E. They’re representatives of the API platform or program. They’re out there supporting other teams.
So a team can go to them instead of everybody coming to that group of three that’s running everything for the organization.
So to give you an idea of the—yeah, it’s fascinating. And to give you an idea, the company I mentioned has 10,000 developers. We have four people in our central COE. And then we have over a hundred coaches. So those coaches are out there doing the work. They’re the ones that understand the domain nuances, the context, the vision, the different systems that it has. It supports them.
So that when an API is being designed, they’re taking all those things into account. But they also know kind of where is our line of business going? Or where is our domain area going? What are our goals? What are our goals for the next quarter, for the next year? And they’re applying all those things. And they’re giving API design advice out there contextually, which is way more valuable than someone who’s never been in that area before, doesn’t understand it at all, looks at the API and says, yeah, that looks great. When in actuality, it really won’t work within the context of that domain because of various reasons—cardinality of calls, or complexity, or standards, interoperability, or all kinds of different things that central group wouldn’t know about.
So it’s not a completely distributed way to do API governance. It’s a federated way. You have your core group. They’re the ones defining the guidance. And then the coaches are out there helping to execute, giving design support and being out there and being an extension of that COE.
And it’s really, really powerful. And it’s something that I’ve been helping a lot of organizations do. It takes a lot of training. So I spend a lot of time training up coaches in organizations. And it also requires you to adjust your governance model just a little bit in the way that you do business day to day with your APIs.
Derric: Makes sense. I really like that approach of trying to take the domain knowledge and marrying that with, I guess, the API design knowledge as well, because, you know, they can be very separate, you know, different folks and everything. Really exciting to talk about the ADDR process here with you, James. Any parting thoughts that you want to share with the audience?
James: Yeah. I would just encourage anyone—anyone listening to this—you’re involved in APIs in some way. You may have a software as a service. You may be launching a startup and you’ve got a startup idea. Or you might be, you know, further on in your business life sector. You might be part of enterprise IT. You’re just trying to figure out how to, you know, observe your APIs and find metrics or report on those—whatever it is.
I would encourage you to start stepping back and thinking about the business aspects of things. We spend a lot of time in tech. And I love, you know, talking about JSON payloads and RFCs and all that—just like any other API nerd out there that just absolutely loves doing that. But when it comes down to it, we’ve got to solve problems.
So stepping back, thinking about that is going to be really key. And if I can, I’ll just drop a quick note that I’ve started to externalize some of this training—a lot of the training about ADDR. So I do a lot for corporate engagements, and I’m happy to talk about that if there’s some sort of engagement that would make sense to help, you know, train up a large group of people.
But if you’re just an individual and you’re just wanting to grow your career too, I’ve launched apicoach.io, where I have training there that’s available on API fundamentals. If you’re a product manager and you just want to learn more, or if you’re a practitioner and you want to dig in and understand how to apply ADDR—I have that as well. So apicoach.io, you can go there and check that out as well. And it’ll cover a lot of the concepts we talked about today in the midst of the training and show you how to do it and what it looks like and let you get hands on and try things out.
Derric: Awesome. Happy to have you here, James. And again, thinking about the outcomes of what a customer cares about and not just—it’s great to debate GraphQL and REST and everything else—but, you know, those are just technologies to achieve an actual outcome.
James: Absolutely. Absolutely. There’s a time and place for it all. It’s good discussion, but in the end, it needs to be solving problems. Just like you said.
Related Articles
API Strategy
API Management: How to Monitor API Usage Across Multiple API Gateways
Monitor API usage across multiple gateways with Moesif. Unify API management, analytics, and billing to improve visibility and scale API products faster.
API Analytics and Monitoring
How to Setup Observability for your MCP Server with Moesif
In this article we’ll discuss how to set up observability to debug your MCP server and understand usage patterns
Podcasts
APIs Over IPAs 18: Platform Engineering and Reducing Operational Overhead with Nuwan Dias, WSO2
In this episode Nuwan Dias of WSO2 joins to explore what effective API lifecycle management really looks like.
API Analytics and Monitoring
Gravitee + Moesif: Unlocking API Observability And Monetization
Learn how you can achieve API observability and API monetization by using Gravitee and Moesif together.